Replace legacy memory system with HierarchicalMemory

Major refactor of the memory module:

- Add hierarchical scoping (user → session → agent → turn)
- Add temporal versioning with supersession support
- Add pluggable adapters (SQLite store, HNSW vectors, FTS5 text search)
- Add protocol interfaces (ports) for all memory components
- Update LRUMemoryCache to implement async MemoryCache protocol
- Update wrapper.py to use HierarchicalMemory backend
- Preserve with_memory() one-liner API with zero-latency inline extraction

New files:
- adapters/: sqlite.py, hnsw.py, fts5.py, cache.py, embedders.py
- core.py: HierarchicalMemory orchestrator
- models.py: Memory, MemoryCategory, ScopeLevel
- ports.py: Protocol interfaces (MemoryStore, VectorIndex, etc.)
- config.py: MemoryConfig with backend selection
- factory.py: Component creation from config

Removed legacy files:
- store.py, fast_store.py, extractor.py, worker.py, fast_wrapper.py

Breaking change: Removes legacy memory API (pre-0.3.0)

headroom/__init__.py

@@ -113,8 +113,16 @@ from .exceptions import (
     ValidationError,
 )
 
-# Memory module - simple, LLM-driven memory
-from .memory import Memory, SQLiteMemoryStore, with_memory
+# Memory module - hierarchical memory system
+from .memory import (
+    EmbedderBackend,
+    HierarchicalMemory,
+    Memory,
+    MemoryCategory,
+    MemoryConfig,
+    ScopeLevel,
+    with_memory,
+)
 from .providers import AnthropicProvider, OpenAIProvider, Provider, TokenCounter
 from .relevance import (
     BM25Scorer,
@@ -135,7 +143,7 @@ from .transforms import (
     TransformPipeline,
 )
 
-__version__ = "0.2.15"
+__version__ = "0.3.0"
 
 __all__ = [
     # Main client
@@ -205,8 +213,12 @@ __all__ = [
     "count_tokens_text",
     "count_tokens_messages",
     "generate_report",
-    # Memory - simple, LLM-driven memory
-    "with_memory",
+    # Memory - hierarchical memory system
+    "with_memory",  # Main user-facing API
     "Memory",
-    "SQLiteMemoryStore",
+    "MemoryCategory",
+    "ScopeLevel",
+    "HierarchicalMemory",
+    "MemoryConfig",
+    "EmbedderBackend",
 ]

headroom/memory/__init__.py

@@ -1,37 +1,108 @@
-"""Headroom Memory - Simple, LLM-driven memory for AI applications.
+"""Headroom Memory - Hierarchical memory system for AI applications.
 
-Two approaches available:
+This module provides a sophisticated memory system with:
+- Hierarchical scoping (user -> session -> agent -> turn)
+- Temporal versioning with supersession
+- Vector and text search capabilities
+- Pluggable storage backends via Protocol interfaces
+- Zero-latency inline memory extraction (Letta-style)
+
+Quick Start (One-liner with any LLM client):
+    from openai import OpenAI
+    from headroom.memory import with_memory
 
-1. Background extraction (original):
-    from headroom import with_memory
     client = with_memory(OpenAI(), user_id="alice")
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "I prefer Python"}]
+    )
+    # Memory automatically extracted and stored!
+
+Advanced Usage (Direct API):
+    from headroom.memory import HierarchicalMemory, MemoryConfig, MemoryCategory
+
+    memory = await HierarchicalMemory.create()
+    await memory.add(
+        content="User prefers Python over JavaScript",
+        user_id="alice",
+        category=MemoryCategory.PREFERENCE,
+    )
+    results = await memory.search("programming preferences", user_id="alice")
 
-2. Zero-latency inline extraction (recommended):
-    from headroom.memory import with_fast_memory
-    client = with_fast_memory(OpenAI(), user_id="alice")
+Configuration:
+    from headroom.memory import MemoryConfig, EmbedderBackend
+
+    config = MemoryConfig(
+        embedder_backend=EmbedderBackend.OPENAI,
+        openai_api_key="sk-...",
+    )
+    memory = await HierarchicalMemory.create(config)
 """
 
-from headroom.memory.fast_store import FastMemoryStore, MemoryChunk
-from headroom.memory.fast_wrapper import with_fast_memory
-from headroom.memory.inline_extractor import (
-    InlineMemoryWrapper,
-    inject_memory_instruction,
-    parse_response_with_memory,
+# Configuration
+from headroom.memory.config import (
+    EmbedderBackend,
+    MemoryConfig,
+    StoreBackend,
+    TextBackend,
+    VectorBackend,
+)
+
+# Core orchestrator
+from headroom.memory.core import HierarchicalMemory
+
+# Factory
+from headroom.memory.factory import create_memory_system
+
+# Data models
+from headroom.memory.models import Memory, MemoryCategory, ScopeLevel
+
+# Protocol interfaces (ports)
+from headroom.memory.ports import (
+    Embedder,
+    MemoryCache,
+    MemoryFilter,
+    MemoryStore,
+    TextFilter,
+    TextIndex,
+    TextSearchResult,
+    VectorFilter,
+    VectorIndex,
+    VectorSearchResult,
 )
-from headroom.memory.store import Memory, SQLiteMemoryStore
-from headroom.memory.wrapper import with_memory
+
+# Wrapper for LLM clients (main user-facing API)
+from headroom.memory.wrapper import MemoryWrapper, with_memory
 
 __all__ = [
-    # Original approach (background extraction)
+    # Main user-facing API
     "with_memory",
+    "MemoryWrapper",
+    # Core orchestrator
+    "HierarchicalMemory",
+    # Data models
     "Memory",
-    "SQLiteMemoryStore",
-    # Fast approach (inline extraction - recommended)
-    "with_fast_memory",
-    "FastMemoryStore",
-    "MemoryChunk",
-    # Low-level inline extraction
-    "InlineMemoryWrapper",
-    "inject_memory_instruction",
-    "parse_response_with_memory",
+    "MemoryCategory",
+    "ScopeLevel",
+    # Protocol interfaces (ports)
+    "MemoryStore",
+    "VectorIndex",
+    "TextIndex",
+    "Embedder",
+    "MemoryCache",
+    # Filter dataclasses
+    "MemoryFilter",
+    "VectorFilter",
+    "TextFilter",
+    # Search result dataclasses
+    "VectorSearchResult",
+    "TextSearchResult",
+    # Configuration
+    "MemoryConfig",
+    "StoreBackend",
+    "VectorBackend",
+    "TextBackend",
+    "EmbedderBackend",
+    # Factory
+    "create_memory_system",
 ]

headroom/memory/adapters/__init__.py

@@ -0,0 +1,73 @@
+"""Memory adapters for Headroom's hierarchical memory system.
+
+This module provides concrete implementations of the memory system's ports:
+- SQLiteMemoryStore: SQLite-based memory persistence
+- FTS5TextIndex: SQLite FTS5 full-text search index
+- HNSWVectorIndex: HNSW-based vector index using hnswlib (optional)
+- LRUMemoryCache: Thread-safe LRU cache for hot memories
+- LocalEmbedder: sentence-transformers embedding (local, optional)
+- OpenAIEmbedder: OpenAI API embedding (cloud, optional)
+- OllamaEmbedder: Ollama API embedding (local server, optional)
+
+Note: Some adapters require optional dependencies. Import errors are
+deferred until the adapter is actually used.
+"""
+
+# Core adapters (no external dependencies beyond sqlite3)
+from headroom.memory.adapters.cache import LRUMemoryCache
+from headroom.memory.adapters.fts5 import FTS5TextIndex
+from headroom.memory.adapters.sqlite import SQLiteMemoryStore
+
+# Lazy imports for optional adapters
+_HNSWVectorIndex = None
+_LocalEmbedder = None
+_OpenAIEmbedder = None
+_OllamaEmbedder = None
+
+
+def __getattr__(name: str) -> type:
+    """Lazy import for optional adapters."""
+    global _HNSWVectorIndex, _LocalEmbedder, _OpenAIEmbedder, _OllamaEmbedder
+
+    if name == "HNSWVectorIndex":
+        if _HNSWVectorIndex is None:
+            from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+            _HNSWVectorIndex = HNSWVectorIndex
+        return _HNSWVectorIndex
+
+    if name == "LocalEmbedder":
+        if _LocalEmbedder is None:
+            from headroom.memory.adapters.embedders import LocalEmbedder
+
+            _LocalEmbedder = LocalEmbedder
+        return _LocalEmbedder
+
+    if name == "OpenAIEmbedder":
+        if _OpenAIEmbedder is None:
+            from headroom.memory.adapters.embedders import OpenAIEmbedder
+
+            _OpenAIEmbedder = OpenAIEmbedder
+        return _OpenAIEmbedder
+
+    if name == "OllamaEmbedder":
+        if _OllamaEmbedder is None:
+            from headroom.memory.adapters.embedders import OllamaEmbedder
+
+            _OllamaEmbedder = OllamaEmbedder
+        return _OllamaEmbedder
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Core adapters (always available)
+    "FTS5TextIndex",
+    "LRUMemoryCache",
+    "SQLiteMemoryStore",
+    # Optional adapters (lazy-loaded)
+    "HNSWVectorIndex",
+    "LocalEmbedder",
+    "OllamaEmbedder",
+    "OpenAIEmbedder",
+]

headroom/memory/adapters/cache.py

@@ -0,0 +1,285 @@
+"""Thread-safe LRU cache for hot memories in Headroom Memory.
+
+Provides O(1) get/set operations with configurable size limits
+and automatic eviction of least-recently-used entries.
+
+Implements the MemoryCache protocol with async methods.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from threading import Lock
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..models import Memory
+
+
+class LRUMemoryCache:
+    """Thread-safe LRU (Least Recently Used) cache for Memory objects.
+
+    Implements the MemoryCache protocol with async methods that wrap
+    synchronous operations.
+
+    Features:
+    - O(1) get and set operations using OrderedDict
+    - Automatic eviction of least-recently-used entries when at capacity
+    - Thread-safe with Lock for concurrent access
+    - Move-to-end on access to maintain LRU ordering
+    - Batch operations for efficiency
+
+    Usage:
+        cache = LRUMemoryCache(max_size=1000)
+        await cache.put(memory_obj)
+        memory = await cache.get("mem-123")  # Returns Memory or None
+
+    The cache uses an OrderedDict internally where:
+    - Most recently used items are at the end
+    - Least recently used items are at the beginning
+    - On capacity overflow, the first (oldest) item is evicted
+    """
+
+    def __init__(self, max_size: int = 1000) -> None:
+        """Initialize the LRU cache.
+
+        Args:
+            max_size: Maximum number of entries to store. When exceeded,
+                      the least recently used entry is evicted.
+
+        Raises:
+            ValueError: If max_size is less than 1.
+        """
+        if max_size < 1:
+            raise ValueError(f"max_size must be at least 1, got {max_size}")
+
+        self._max_size = max_size
+        self._cache: OrderedDict[str, Memory] = OrderedDict()
+        self._lock = Lock()
+
+    async def get(self, memory_id: str) -> Memory | None:
+        """Get a memory from the cache.
+
+        Moves the accessed item to the end (most recently used position).
+
+        Args:
+            memory_id: The memory ID to retrieve.
+
+        Returns:
+            The Memory object if found, None otherwise.
+        """
+        with self._lock:
+            if memory_id not in self._cache:
+                return None
+
+            # Move to end (most recently used)
+            self._cache.move_to_end(memory_id)
+            return self._cache[memory_id]
+
+    async def get_batch(self, memory_ids: list[str]) -> dict[str, Memory]:
+        """Get multiple memories from the cache.
+
+        Moves all accessed items to the end in the order they were requested.
+
+        Args:
+            memory_ids: List of memory IDs to retrieve.
+
+        Returns:
+            Dict mapping memory IDs to Memory objects for all found in cache.
+            IDs not in cache are omitted from the result.
+        """
+        with self._lock:
+            result: dict[str, Memory] = {}
+            for memory_id in memory_ids:
+                if memory_id in self._cache:
+                    # Move to end (most recently used)
+                    self._cache.move_to_end(memory_id)
+                    result[memory_id] = self._cache[memory_id]
+            return result
+
+    async def put(
+        self,
+        memory: Memory,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Put a memory in the cache.
+
+        If the memory already exists, updates the value and moves to end.
+        If at capacity, evicts the least recently used entry first.
+
+        Args:
+            memory: The Memory object to cache.
+            ttl_seconds: Time-to-live in seconds. Currently ignored in this
+                         basic LRU implementation (reserved for future use).
+        """
+        # Note: ttl_seconds is accepted but ignored in this basic LRU implementation.
+        # A TTL-aware version would need a background cleanup thread or lazy expiration.
+        _ = ttl_seconds  # Explicitly ignore
+
+        with self._lock:
+            key = memory.id
+            if key in self._cache:
+                # Update existing entry and move to end
+                self._cache[key] = memory
+                self._cache.move_to_end(key)
+            else:
+                # Add new entry
+                self._cache[key] = memory
+
+                # Evict oldest if at capacity
+                while len(self._cache) > self._max_size:
+                    # popitem(last=False) removes the first (oldest) item
+                    self._cache.popitem(last=False)
+
+    async def put_batch(
+        self,
+        memories: list[Memory],
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Put multiple memories in the cache.
+
+        Args:
+            memories: List of Memory objects to cache.
+            ttl_seconds: Time-to-live in seconds. Currently ignored in this
+                         basic LRU implementation (reserved for future use).
+        """
+        # Note: ttl_seconds is accepted but ignored in this basic LRU implementation.
+        _ = ttl_seconds  # Explicitly ignore
+
+        with self._lock:
+            for memory in memories:
+                key = memory.id
+                if key in self._cache:
+                    self._cache[key] = memory
+                    self._cache.move_to_end(key)
+                else:
+                    self._cache[key] = memory
+
+            # Evict oldest entries if over capacity
+            while len(self._cache) > self._max_size:
+                self._cache.popitem(last=False)
+
+    async def invalidate(self, memory_id: str) -> bool:
+        """Invalidate (remove) a memory from cache.
+
+        Args:
+            memory_id: The memory ID to remove.
+
+        Returns:
+            True if the memory was in cache, False otherwise.
+        """
+        with self._lock:
+            if memory_id in self._cache:
+                del self._cache[memory_id]
+                return True
+            return False
+
+    async def invalidate_batch(self, memory_ids: list[str]) -> int:
+        """Invalidate multiple memories from cache.
+
+        Args:
+            memory_ids: List of memory IDs to invalidate.
+
+        Returns:
+            Number of memories that were in cache.
+        """
+        with self._lock:
+            count = 0
+            for memory_id in memory_ids:
+                if memory_id in self._cache:
+                    del self._cache[memory_id]
+                    count += 1
+            return count
+
+    async def invalidate_scope(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> int:
+        """Invalidate all cached memories at or below a scope.
+
+        Args:
+            user_id: Required user scope.
+            session_id: If provided, invalidate session and below.
+            agent_id: If provided, invalidate agent and below.
+
+        Returns:
+            Number of memories invalidated.
+        """
+        with self._lock:
+            # Find all matching memory IDs
+            to_remove = []
+            for memory_id, memory in self._cache.items():
+                if memory.user_id != user_id:
+                    continue
+                if session_id is not None and memory.session_id != session_id:
+                    continue
+                if agent_id is not None and memory.agent_id != agent_id:
+                    continue
+                to_remove.append(memory_id)
+
+            # Remove them
+            for memory_id in to_remove:
+                del self._cache[memory_id]
+
+            return len(to_remove)
+
+    async def clear(self) -> None:
+        """Remove all entries from the cache."""
+        with self._lock:
+            self._cache.clear()
+
+    @property
+    def size(self) -> int:
+        """Get the current number of entries in the cache.
+
+        Returns:
+            Number of entries currently stored.
+        """
+        with self._lock:
+            return len(self._cache)
+
+    @property
+    def max_size(self) -> int | None:
+        """Get the maximum cache size.
+
+        Returns:
+            Maximum number of entries allowed.
+        """
+        return self._max_size
+
+    def contains(self, memory_id: str) -> bool:
+        """Check if a memory exists in the cache without affecting LRU order.
+
+        Args:
+            memory_id: The memory ID to check.
+
+        Returns:
+            True if the memory exists, False otherwise.
+        """
+        with self._lock:
+            return memory_id in self._cache
+
+    def keys(self) -> list[str]:
+        """Get all keys in the cache.
+
+        Returns:
+            List of keys in LRU order (oldest first, newest last).
+        """
+        with self._lock:
+            return list(self._cache.keys())
+
+    def stats(self) -> dict:
+        """Get cache statistics.
+
+        Returns:
+            Dict with size, max_size, and utilization percentage.
+        """
+        with self._lock:
+            current_size = len(self._cache)
+            return {
+                "size": current_size,
+                "max_size": self._max_size,
+                "utilization": (current_size / self._max_size) * 100 if self._max_size > 0 else 0.0,
+            }

headroom/memory/adapters/embedders.py

@@ -0,0 +1,716 @@
+"""Embedder implementations for Headroom Memory.
+
+Provides embedding generation via multiple backends:
+- LocalEmbedder: sentence-transformers (local, no API needed)
+- OpenAIEmbedder: OpenAI API (cloud, requires API key)
+- OllamaEmbedder: Ollama API (local server)
+
+All embedders return normalized float32 vectors for cosine similarity.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_embedding(embedding: np.ndarray) -> np.ndarray:
+    """Normalize embedding to unit vector for cosine similarity.
+
+    Args:
+        embedding: The embedding vector to normalize.
+
+    Returns:
+        Normalized embedding with L2 norm of 1.0.
+    """
+    norm = np.linalg.norm(embedding)
+    if norm > 0:
+        result: np.ndarray = (embedding / norm).astype(np.float32)
+        return result
+    result = embedding.astype(np.float32)
+    return result
+
+
+def _normalize_embeddings_batch(embeddings: np.ndarray) -> np.ndarray:
+    """Normalize a batch of embeddings to unit vectors.
+
+    Args:
+        embeddings: 2D array of embeddings (batch_size, dimension).
+
+    Returns:
+        Normalized embeddings with L2 norm of 1.0 per row.
+    """
+    norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+    # Avoid division by zero
+    norms = np.where(norms > 0, norms, 1.0)
+    return (embeddings / norms).astype(np.float32)
+
+
+# =============================================================================
+# LocalEmbedder - sentence-transformers
+# =============================================================================
+
+
+class LocalEmbedder:
+    """Local embedding using sentence-transformers.
+
+    Uses the sentence-transformers library for local embedding generation.
+    No API calls needed - runs entirely on local hardware.
+
+    Features:
+    - Lazy model loading (loads on first use)
+    - Automatic device selection (CUDA > MPS > CPU)
+    - Batch embedding support
+    - Returns normalized float32 vectors
+
+    Default model: all-MiniLM-L6-v2 (384 dimensions)
+
+    Usage:
+        embedder = LocalEmbedder()
+        embedding = await embedder.embed("Hello world")
+        embeddings = await embedder.embed_batch(["Hello", "World"])
+    """
+
+    DEFAULT_MODEL = "all-MiniLM-L6-v2"
+    DEFAULT_DIMENSION = 384
+    DEFAULT_MAX_TOKENS = 256
+
+    def __init__(
+        self,
+        model_name: str | None = None,
+        device: str | None = None,
+    ) -> None:
+        """Initialize the local embedder.
+
+        Args:
+            model_name: Name of the sentence-transformers model to use.
+                       Defaults to "all-MiniLM-L6-v2".
+            device: Device to run on ("cuda", "mps", "cpu", or None for auto).
+                   If None, automatically selects the best available device.
+
+        Raises:
+            ImportError: If sentence-transformers is not installed.
+        """
+        self._model_name = model_name or self.DEFAULT_MODEL
+        self._requested_device = device
+        self._model: SentenceTransformer | None = None
+        self._device: str | None = None
+        self._dimension: int | None = None
+        self._lock = asyncio.Lock()
+
+    def _check_dependencies(self) -> None:
+        """Check that required dependencies are installed."""
+        try:
+            import sentence_transformers  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "sentence-transformers is required for LocalEmbedder. "
+                "Install it with: pip install sentence-transformers"
+            ) from e
+
+    def _detect_device(self) -> str:
+        """Auto-detect the best available device.
+
+        Returns:
+            Device string: "cuda", "mps", or "cpu".
+        """
+        import torch
+
+        if torch.cuda.is_available():
+            logger.info("CUDA device detected, using GPU")
+            return "cuda"
+        elif torch.backends.mps.is_available():
+            logger.info("MPS device detected, using Apple Silicon GPU")
+            return "mps"
+        else:
+            logger.info("No GPU detected, using CPU")
+            return "cpu"
+
+    def _load_model(self) -> None:
+        """Load the sentence-transformers model lazily."""
+        if self._model is not None:
+            return
+
+        self._check_dependencies()
+        from sentence_transformers import SentenceTransformer
+
+        # Determine device
+        if self._requested_device:
+            self._device = self._requested_device
+        else:
+            self._device = self._detect_device()
+
+        logger.info(f"Loading model {self._model_name} on device {self._device}")
+        self._model = SentenceTransformer(self._model_name, device=self._device)
+
+        # Get actual dimension from loaded model
+        self._dimension = self._model.get_sentence_embedding_dimension()
+        logger.info(
+            f"Model loaded: {self._model_name}, dimension={self._dimension}, device={self._device}"
+        )
+
+    async def embed(self, text: str) -> np.ndarray:
+        """Generate an embedding for a single text.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            Normalized embedding vector as float32 numpy array.
+        """
+        async with self._lock:
+            # Load model if not already loaded
+            if self._model is None:
+                await asyncio.get_event_loop().run_in_executor(None, self._load_model)
+
+        # Handle empty string
+        if not text or not text.strip():
+            return np.zeros(self.dimension, dtype=np.float32)
+
+        # Run encoding in executor to avoid blocking
+        # Model is guaranteed to be loaded after the lock check above
+        assert self._model is not None
+        model = self._model  # Local reference for lambda closure
+        loop = asyncio.get_event_loop()
+        embedding = await loop.run_in_executor(
+            None,
+            lambda: model.encode(text, convert_to_numpy=True, normalize_embeddings=False),
+        )
+
+        return _normalize_embedding(embedding)
+
+    async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
+        """Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of normalized embedding vectors.
+        """
+        if not texts:
+            return []
+
+        async with self._lock:
+            # Load model if not already loaded
+            if self._model is None:
+                await asyncio.get_event_loop().run_in_executor(None, self._load_model)
+
+        # Handle empty strings by tracking their indices
+        non_empty_indices = []
+        non_empty_texts = []
+        for i, text in enumerate(texts):
+            if text and text.strip():
+                non_empty_indices.append(i)
+                non_empty_texts.append(text)
+
+        # Initialize results with zeros for empty strings
+        results: list[np.ndarray] = [
+            np.zeros(self.dimension, dtype=np.float32) for _ in range(len(texts))
+        ]
+
+        if non_empty_texts:
+            # Run batch encoding in executor
+            # Model is guaranteed to be loaded after the lock check above
+            assert self._model is not None
+            model = self._model  # Local reference for lambda closure
+            loop = asyncio.get_event_loop()
+            embeddings = await loop.run_in_executor(
+                None,
+                lambda: model.encode(
+                    non_empty_texts, convert_to_numpy=True, normalize_embeddings=False
+                ),
+            )
+
+            # Normalize batch
+            normalized = _normalize_embeddings_batch(embeddings)
+
+            # Place results at correct indices
+            for idx, emb in zip(non_empty_indices, normalized):
+                results[idx] = emb
+
+        return results
+
+    @property
+    def dimension(self) -> int:
+        """Return the dimension of generated embeddings."""
+        if self._dimension is not None:
+            return self._dimension
+        # Return default dimension before model is loaded
+        return self.DEFAULT_DIMENSION
+
+    @property
+    def model_name(self) -> str:
+        """Return the name of the embedding model."""
+        return self._model_name
+
+    @property
+    def max_tokens(self) -> int:
+        """Return the maximum number of tokens the model can process."""
+        return self.DEFAULT_MAX_TOKENS
+
+
+# =============================================================================
+# OpenAIEmbedder - OpenAI API
+# =============================================================================
+
+
+class OpenAIEmbedder:
+    """OpenAI API-based embedding generation.
+
+    Uses OpenAI's text-embedding-3-small model for high-quality embeddings.
+    Requires an API key (constructor parameter or OPENAI_API_KEY env var).
+
+    Features:
+    - Async API calls with retry logic
+    - Batch support with automatic rate limiting
+    - Returns normalized float32 vectors
+
+    Default model: text-embedding-3-small (1536 dimensions)
+
+    Usage:
+        embedder = OpenAIEmbedder(api_key="sk-...")
+        # Or use OPENAI_API_KEY environment variable
+        embedder = OpenAIEmbedder()
+        embedding = await embedder.embed("Hello world")
+    """
+
+    DEFAULT_MODEL = "text-embedding-3-small"
+    DEFAULT_DIMENSION = 1536
+    DEFAULT_MAX_TOKENS = 8191
+    MAX_BATCH_SIZE = 2048  # OpenAI's limit
+    MAX_RETRIES = 3
+    RETRY_DELAY_BASE = 1.0  # Base delay in seconds for exponential backoff
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model_name: str | None = None,
+        max_retries: int | None = None,
+    ) -> None:
+        """Initialize the OpenAI embedder.
+
+        Args:
+            api_key: OpenAI API key. If not provided, will use OPENAI_API_KEY
+                    environment variable.
+            model_name: Model to use. Defaults to "text-embedding-3-small".
+            max_retries: Maximum number of retries for transient failures.
+
+        Raises:
+            ImportError: If openai library is not installed.
+            ValueError: If no API key is provided or found in environment.
+        """
+        self._check_dependencies()
+
+        self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not self._api_key:
+            raise ValueError(
+                "OpenAI API key required. Provide api_key parameter or set "
+                "OPENAI_API_KEY environment variable."
+            )
+
+        self._model_name = model_name or self.DEFAULT_MODEL
+        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES
+        self._client = None
+
+    def _check_dependencies(self) -> None:
+        """Check that required dependencies are installed."""
+        try:
+            import openai  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "openai is required for OpenAIEmbedder. Install it with: pip install openai"
+            ) from e
+
+    @cached_property
+    def _async_client(self) -> Any:
+        """Lazy initialization of async OpenAI client."""
+        from openai import AsyncOpenAI
+
+        return AsyncOpenAI(api_key=self._api_key)
+
+    async def _embed_with_retry(self, texts: list[str]) -> list[np.ndarray]:
+        """Call OpenAI API with retry logic for transient failures.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of embedding vectors.
+
+        Raises:
+            ConnectionError: If all retries fail.
+        """
+        from openai import APIConnectionError, APITimeoutError, RateLimitError
+
+        last_error = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = await self._async_client.embeddings.create(
+                    model=self._model_name,
+                    input=texts,
+                )
+                # Extract embeddings in order
+                embeddings = [np.array(item.embedding, dtype=np.float32) for item in response.data]
+                return embeddings
+
+            except (APIConnectionError, APITimeoutError, RateLimitError) as e:
+                last_error = e
+                delay = self.RETRY_DELAY_BASE * (2**attempt)
+                logger.warning(
+                    f"OpenAI API error (attempt {attempt + 1}/{self._max_retries}): {e}. "
+                    f"Retrying in {delay:.1f}s..."
+                )
+                await asyncio.sleep(delay)
+
+            except Exception as e:
+                # Non-retryable error
+                raise ConnectionError(f"OpenAI API error: {e}") from e
+
+        # All retries exhausted
+        raise ConnectionError(
+            f"OpenAI API failed after {self._max_retries} retries: {last_error}"
+        ) from last_error
+
+    async def embed(self, text: str) -> np.ndarray:
+        """Generate an embedding for a single text.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            Normalized embedding vector as float32 numpy array.
+
+        Raises:
+            ConnectionError: If API call fails after retries.
+        """
+        # Handle empty string
+        if not text or not text.strip():
+            return np.zeros(self.dimension, dtype=np.float32)
+
+        embeddings = await self._embed_with_retry([text])
+        return _normalize_embedding(embeddings[0])
+
+    async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
+        """Generate embeddings for multiple texts.
+
+        Automatically handles batching for large inputs.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of normalized embedding vectors.
+
+        Raises:
+            ConnectionError: If API call fails after retries.
+        """
+        if not texts:
+            return []
+
+        # Handle empty strings by tracking their indices
+        non_empty_indices = []
+        non_empty_texts = []
+        for i, text in enumerate(texts):
+            if text and text.strip():
+                non_empty_indices.append(i)
+                non_empty_texts.append(text)
+
+        # Initialize results with zeros for empty strings
+        results: list[np.ndarray] = [
+            np.zeros(self.dimension, dtype=np.float32) for _ in range(len(texts))
+        ]
+
+        if not non_empty_texts:
+            return results
+
+        # Process in batches
+        all_embeddings: list[np.ndarray] = []
+        for batch_start in range(0, len(non_empty_texts), self.MAX_BATCH_SIZE):
+            batch_end = min(batch_start + self.MAX_BATCH_SIZE, len(non_empty_texts))
+            batch = non_empty_texts[batch_start:batch_end]
+
+            batch_embeddings = await self._embed_with_retry(batch)
+            all_embeddings.extend(batch_embeddings)
+
+        # Normalize and place results at correct indices
+        for idx, emb in zip(non_empty_indices, all_embeddings):
+            results[idx] = _normalize_embedding(emb)
+
+        return results
+
+    @property
+    def dimension(self) -> int:
+        """Return the dimension of generated embeddings."""
+        return self.DEFAULT_DIMENSION
+
+    @property
+    def model_name(self) -> str:
+        """Return the name of the embedding model."""
+        return self._model_name
+
+    @property
+    def max_tokens(self) -> int:
+        """Return the maximum number of tokens the model can process."""
+        return self.DEFAULT_MAX_TOKENS
+
+
+# =============================================================================
+# OllamaEmbedder - Ollama API
+# =============================================================================
+
+
+class OllamaEmbedder:
+    """Ollama API-based embedding generation.
+
+    Uses a local Ollama server for embedding generation. No cloud API needed.
+
+    Features:
+    - Async HTTP calls via httpx
+    - Batch support
+    - Retry logic for transient failures
+    - Returns normalized float32 vectors
+
+    Default model: nomic-embed-text (768 dimensions)
+
+    Usage:
+        embedder = OllamaEmbedder()  # Uses localhost:11434
+        embedder = OllamaEmbedder(base_url="http://remote:11434")
+        embedding = await embedder.embed("Hello world")
+    """
+
+    DEFAULT_MODEL = "nomic-embed-text"
+    DEFAULT_DIMENSION = 768
+    DEFAULT_MAX_TOKENS = 8192
+    DEFAULT_BASE_URL = "http://localhost:11434"
+    MAX_RETRIES = 3
+    RETRY_DELAY_BASE = 0.5  # Base delay in seconds for exponential backoff
+    REQUEST_TIMEOUT = 60.0  # Timeout for API requests
+
+    # Known model dimensions (for models that don't report their dimension)
+    KNOWN_DIMENSIONS = {
+        "nomic-embed-text": 768,
+        "all-minilm": 384,
+        "mxbai-embed-large": 1024,
+    }
+
+    def __init__(
+        self,
+        model_name: str | None = None,
+        base_url: str | None = None,
+        max_retries: int | None = None,
+        dimension: int | None = None,
+    ) -> None:
+        """Initialize the Ollama embedder.
+
+        Args:
+            model_name: Model to use. Defaults to "nomic-embed-text".
+            base_url: Ollama server URL. Defaults to "http://localhost:11434".
+            max_retries: Maximum number of retries for transient failures.
+            dimension: Override embedding dimension. If not provided, uses
+                      known dimension for model or probes the API.
+
+        Raises:
+            ImportError: If httpx library is not installed.
+        """
+        self._check_dependencies()
+
+        self._model_name = model_name or self.DEFAULT_MODEL
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES
+        self._explicit_dimension = dimension
+        self._detected_dimension: int | None = None
+        self._client: Any = None  # httpx.AsyncClient when initialized
+        self._lock = asyncio.Lock()
+
+    def _check_dependencies(self) -> None:
+        """Check that required dependencies are installed."""
+        try:
+            import httpx  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "httpx is required for OllamaEmbedder. Install it with: pip install httpx"
+            ) from e
+
+    async def _get_client(self) -> Any:
+        """Get or create the httpx async client."""
+        if self._client is None:
+            import httpx
+
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self.REQUEST_TIMEOUT,
+            )
+        return self._client
+
+    async def _embed_single_with_retry(self, text: str) -> np.ndarray:
+        """Call Ollama API with retry logic for a single text.
+
+        Args:
+            text: Text to embed.
+
+        Returns:
+            Embedding vector.
+
+        Raises:
+            ConnectionError: If all retries fail.
+        """
+        import httpx
+
+        client = await self._get_client()
+        last_error = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = await client.post(
+                    "/api/embeddings",
+                    json={
+                        "model": self._model_name,
+                        "prompt": text,
+                    },
+                )
+                response.raise_for_status()
+
+                data = response.json()
+                embedding = np.array(data["embedding"], dtype=np.float32)
+
+                # Detect dimension from first successful response
+                if self._detected_dimension is None:
+                    self._detected_dimension = len(embedding)
+
+                return embedding
+
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError) as e:
+                last_error = e
+                delay = self.RETRY_DELAY_BASE * (2**attempt)
+                logger.warning(
+                    f"Ollama API error (attempt {attempt + 1}/{self._max_retries}): {e}. "
+                    f"Retrying in {delay:.1f}s..."
+                )
+                await asyncio.sleep(delay)
+
+            except Exception as e:
+                # Non-retryable error
+                raise ConnectionError(f"Ollama API error: {e}") from e
+
+        # All retries exhausted
+        raise ConnectionError(
+            f"Ollama API failed after {self._max_retries} retries: {last_error}"
+        ) from last_error
+
+    async def embed(self, text: str) -> np.ndarray:
+        """Generate an embedding for a single text.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            Normalized embedding vector as float32 numpy array.
+
+        Raises:
+            ConnectionError: If API call fails after retries.
+        """
+        # Handle empty string
+        if not text or not text.strip():
+            return np.zeros(self.dimension, dtype=np.float32)
+
+        embedding = await self._embed_single_with_retry(text)
+        return _normalize_embedding(embedding)
+
+    async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
+        """Generate embeddings for multiple texts.
+
+        Ollama API doesn't support batch embedding natively,
+        so we make concurrent requests.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of normalized embedding vectors.
+
+        Raises:
+            ConnectionError: If API call fails after retries.
+        """
+        if not texts:
+            return []
+
+        # Handle empty strings by tracking their indices
+        non_empty_indices = []
+        non_empty_texts = []
+        for i, text in enumerate(texts):
+            if text and text.strip():
+                non_empty_indices.append(i)
+                non_empty_texts.append(text)
+
+        # Initialize results with zeros for empty strings
+        results: list[np.ndarray] = [
+            np.zeros(self.dimension, dtype=np.float32) for _ in range(len(texts))
+        ]
+
+        if not non_empty_texts:
+            return results
+
+        # Make concurrent requests for non-empty texts
+        # Use a semaphore to limit concurrency and avoid overwhelming the server
+        semaphore = asyncio.Semaphore(10)
+
+        async def embed_with_semaphore(text: str) -> np.ndarray:
+            async with semaphore:
+                return await self._embed_single_with_retry(text)
+
+        tasks = [embed_with_semaphore(text) for text in non_empty_texts]
+        embeddings = await asyncio.gather(*tasks)
+
+        # Normalize and place results at correct indices
+        for idx, emb in zip(non_empty_indices, embeddings):
+            results[idx] = _normalize_embedding(emb)
+
+        return results
+
+    @property
+    def dimension(self) -> int:
+        """Return the dimension of generated embeddings."""
+        # Priority: explicit > detected > known > default
+        if self._explicit_dimension is not None:
+            return self._explicit_dimension
+        if self._detected_dimension is not None:
+            return self._detected_dimension
+        if self._model_name in self.KNOWN_DIMENSIONS:
+            return self.KNOWN_DIMENSIONS[self._model_name]
+        return self.DEFAULT_DIMENSION
+
+    @property
+    def model_name(self) -> str:
+        """Return the name of the embedding model."""
+        return self._model_name
+
+    @property
+    def max_tokens(self) -> int:
+        """Return the maximum number of tokens the model can process."""
+        return self.DEFAULT_MAX_TOKENS
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> OllamaEmbedder:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()

headroom/memory/adapters/fts5.py

@@ -0,0 +1,478 @@
+"""SQLite FTS5 full-text search index for Headroom Memory.
+
+Provides fast, local full-text search with BM25 ranking.
+Uses SQLite's built-in FTS5 extension with Porter stemming
+and Unicode tokenization for high-quality search results.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..models import Memory, MemoryCategory
+from ..ports import TextFilter, TextSearchResult
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class FTS5SearchResult:
+    """Result from an FTS5 full-text search.
+
+    This is a lightweight result that contains just the indexed fields,
+    not the full Memory object. Use memory_id to fetch the full Memory
+    from the MemoryStore if needed.
+    """
+
+    memory_id: str
+    content: str
+    score: float  # BM25 relevance score (higher = more relevant)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class FTS5TextIndex:
+    """SQLite FTS5 full-text search index.
+
+    Features:
+    - BM25 ranking for relevance scoring
+    - Porter stemming for morphological matching
+    - Unicode support for international text
+    - Filtering by user_id, session_id, and categories
+    - Batch indexing for efficiency
+
+    Usage:
+        index = FTS5TextIndex("./search.db")
+        index.index("mem-123", "User prefers Python", {"user_id": "alice"})
+        results = index.search("python programming", k=5)
+
+    The FTS5 table stores:
+    - memory_id: Unique identifier for the memory
+    - content: Searchable text content
+    - user_id: Optional user identifier for filtering
+    - session_id: Optional session identifier for filtering
+    - category: Memory category for filtering
+    """
+
+    def __init__(self, db_path: str | Path = "headroom_memory.db") -> None:
+        """Initialize the FTS5 text index.
+
+        Args:
+            db_path: Path to SQLite database file. Created if it doesn't exist.
+        """
+        self.db_path = Path(db_path)
+        self._init_db()
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a new database connection (thread-safe pattern).
+
+        Returns:
+            A new SQLite connection with row factory configured.
+        """
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        """Initialize the FTS5 virtual table schema."""
+        with self._get_conn() as conn:
+            # Create FTS5 virtual table with Porter stemming and Unicode tokenization
+            conn.execute("""
+                CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+                    memory_id,
+                    content,
+                    user_id,
+                    session_id,
+                    category,
+                    tokenize='porter unicode61'
+                )
+            """)
+            conn.commit()
+
+    def index_raw(
+        self,
+        memory_id: str,
+        text: str,
+        metadata: dict | None = None,
+    ) -> None:
+        """Index a single memory for full-text search (low-level).
+
+        Args:
+            memory_id: Unique identifier for the memory.
+            text: Text content to index.
+            metadata: Optional metadata dict with user_id, session_id, category.
+        """
+        metadata = metadata or {}
+        user_id = metadata.get("user_id", "")
+        session_id = metadata.get("session_id", "")
+        category = metadata.get("category", "")
+
+        # Handle MemoryCategory enum values
+        if isinstance(category, MemoryCategory):
+            category = category.value
+
+        with self._get_conn() as conn:
+            # Delete existing entry if present (upsert behavior)
+            conn.execute(
+                "DELETE FROM memory_fts WHERE memory_id = ?",
+                (memory_id,),
+            )
+
+            # Insert new entry
+            conn.execute(
+                """
+                INSERT INTO memory_fts (memory_id, content, user_id, session_id, category)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (memory_id, text, user_id, session_id, category),
+            )
+            conn.commit()
+
+    # Alias for backwards compatibility
+    def index(
+        self,
+        memory_id: str,
+        text: str,
+        metadata: dict | None = None,
+    ) -> None:
+        """Index a single memory for full-text search.
+
+        Alias for index_raw for backwards compatibility.
+        For protocol-compliant async indexing, use index_memory().
+        """
+        self.index_raw(memory_id, text, metadata)
+
+    def index_batch(
+        self,
+        memory_ids: list[str],
+        texts: list[str],
+        metadata: list[dict] | None = None,
+    ) -> None:
+        """Index multiple memories in a single transaction.
+
+        Args:
+            memory_ids: List of unique identifiers.
+            texts: List of text contents to index.
+            metadata: Optional list of metadata dicts (one per memory).
+
+        Raises:
+            ValueError: If memory_ids and texts have different lengths.
+        """
+        if len(memory_ids) != len(texts):
+            raise ValueError(
+                f"memory_ids ({len(memory_ids)}) and texts ({len(texts)}) must have same length"
+            )
+
+        if metadata is not None and len(metadata) != len(memory_ids):
+            raise ValueError(
+                f"metadata ({len(metadata)}) must match memory_ids ({len(memory_ids)}) length"
+            )
+
+        metadata = metadata or [{} for _ in memory_ids]
+
+        with self._get_conn() as conn:
+            # Delete existing entries
+            conn.executemany(
+                "DELETE FROM memory_fts WHERE memory_id = ?",
+                [(mid,) for mid in memory_ids],
+            )
+
+            # Prepare batch data
+            batch_data = []
+            for memory_id, text, meta in zip(memory_ids, texts, metadata):
+                user_id = meta.get("user_id", "")
+                session_id = meta.get("session_id", "")
+                category = meta.get("category", "")
+
+                if isinstance(category, MemoryCategory):
+                    category = category.value
+
+                batch_data.append((memory_id, text, user_id, session_id, category))
+
+            # Insert all entries
+            conn.executemany(
+                """
+                INSERT INTO memory_fts (memory_id, content, user_id, session_id, category)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                batch_data,
+            )
+            conn.commit()
+
+    def search(
+        self,
+        query: str,
+        k: int = 10,
+        filter: TextFilter | None = None,
+    ) -> list[FTS5SearchResult]:
+        """Search indexed memories using FTS5 with BM25 ranking.
+
+        Args:
+            query: Search query string.
+            k: Maximum number of results to return.
+            filter: Optional filter for user_id, session_id, categories.
+
+        Returns:
+            List of FTS5SearchResult ordered by BM25 relevance score.
+        """
+        # Sanitize query for FTS5
+        fts_query = self._sanitize_fts_query(query)
+        if not fts_query.strip():
+            return []
+
+        # Build WHERE clause with filters
+        where_clauses = ["memory_fts MATCH ?"]
+        params: list = [fts_query]
+
+        if filter is not None:
+            if filter.user_id is not None:
+                where_clauses.append("user_id = ?")
+                params.append(filter.user_id)
+
+            if filter.session_id is not None:
+                where_clauses.append("session_id = ?")
+                params.append(filter.session_id)
+
+            if filter.categories is not None and len(filter.categories) > 0:
+                # Handle enum values
+                category_values = []
+                for cat in filter.categories:
+                    if isinstance(cat, MemoryCategory):
+                        category_values.append(cat.value)
+                    else:
+                        category_values.append(cat)
+
+                placeholders = ", ".join("?" * len(category_values))
+                where_clauses.append(f"category IN ({placeholders})")
+                params.extend(category_values)
+
+        params.append(k)
+        where_sql = " AND ".join(where_clauses)
+
+        with self._get_conn() as conn:
+            # Query with BM25 ranking (lower is better, so we order ASC)
+            cursor = conn.execute(
+                f"""
+                SELECT memory_id, content, user_id, session_id, category,
+                       bm25(memory_fts) as rank
+                FROM memory_fts
+                WHERE {where_sql}
+                ORDER BY rank
+                LIMIT ?
+                """,
+                params,
+            )
+
+            results = []
+            for row in cursor:
+                # Convert BM25 score to a positive relevance score
+                # BM25 returns negative values where more negative = more relevant
+                # We negate and normalize to make higher = more relevant
+                bm25_score = row["rank"]
+                relevance_score = -bm25_score if bm25_score < 0 else 0.0
+
+                results.append(
+                    FTS5SearchResult(
+                        memory_id=row["memory_id"],
+                        content=row["content"],
+                        score=relevance_score,
+                        metadata={
+                            "user_id": row["user_id"],
+                            "session_id": row["session_id"],
+                            "category": row["category"],
+                        },
+                    )
+                )
+
+            return results
+
+    def delete(self, memory_id: str) -> bool:
+        """Delete a memory from the index.
+
+        Args:
+            memory_id: ID of the memory to delete.
+
+        Returns:
+            True if the memory was deleted, False if not found.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "DELETE FROM memory_fts WHERE memory_id = ?",
+                (memory_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def _sanitize_fts_query(self, query: str) -> str:
+        """Sanitize a query string for FTS5.
+
+        Escapes special characters and handles edge cases for safe querying.
+
+        Args:
+            query: Raw user query string.
+
+        Returns:
+            FTS5-safe query string with OR between terms.
+        """
+        # Extract alphanumeric words
+        words = re.findall(r"\w+", query)
+
+        if not words:
+            return ""
+
+        # Quote each word to handle special characters
+        # Use OR between words for flexible matching
+        escaped_words = [f'"{word}"' for word in words]
+        return " OR ".join(escaped_words)
+
+    def clear(self) -> None:
+        """Clear all entries from the index."""
+        with self._get_conn() as conn:
+            conn.execute("DELETE FROM memory_fts")
+            conn.commit()
+
+    def count(self) -> int:
+        """Get the total number of indexed entries.
+
+        Returns:
+            Number of entries in the index.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute("SELECT COUNT(*) FROM memory_fts")
+            result = cursor.fetchone()[0]
+            return int(result)
+
+    # =========================================================================
+    # Protocol-compliant async methods (TextIndex protocol)
+    # =========================================================================
+
+    async def index_memory(self, memory: Memory) -> None:
+        """Index a memory for full-text search (protocol-compliant).
+
+        Args:
+            memory: The memory to index.
+        """
+        metadata = {
+            "user_id": memory.user_id,
+            "session_id": memory.session_id or "",
+            "category": memory.category,
+        }
+        self.index(memory.id, memory.content, metadata)
+
+    async def index_batch_memories(self, memories: list[Memory]) -> int:
+        """Index multiple memories for full-text search (protocol-compliant).
+
+        Args:
+            memories: List of memories to index.
+
+        Returns:
+            Number of memories indexed.
+        """
+        if not memories:
+            return 0
+
+        memory_ids = [m.id for m in memories]
+        texts = [m.content for m in memories]
+        metadata_list = [
+            {
+                "user_id": m.user_id,
+                "session_id": m.session_id or "",
+                "category": m.category,
+            }
+            for m in memories
+        ]
+        self.index_batch(memory_ids, texts, metadata_list)
+        return len(memories)
+
+    async def remove(self, memory_id: str) -> bool:
+        """Remove a memory from the text index (protocol-compliant).
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        return self.delete(memory_id)
+
+    async def remove_batch(self, memory_ids: list[str]) -> int:
+        """Remove multiple memories from the text index (protocol-compliant).
+
+        Args:
+            memory_ids: List of memory IDs to remove.
+
+        Returns:
+            Number of memories actually removed.
+        """
+        count = 0
+        for memory_id in memory_ids:
+            if self.delete(memory_id):
+                count += 1
+        return count
+
+    async def search_memories(
+        self, filter: TextFilter, store: Any = None
+    ) -> list[TextSearchResult]:
+        """Search for memories using full-text search (protocol-compliant).
+
+        Args:
+            filter: Text search filter with query and constraints.
+            store: Optional MemoryStore to fetch full Memory objects.
+
+        Returns:
+            List of TextSearchResult sorted by relevance.
+        """
+        # Use the existing synchronous search
+        fts_results = self.search(filter.query, k=filter.limit, filter=filter)
+
+        results: list[TextSearchResult] = []
+        for rank, fts_result in enumerate(fts_results, start=1):
+            # Create a minimal Memory object from FTS data
+            # If store is provided, we could fetch the full Memory
+            memory = Memory(
+                id=fts_result.memory_id,
+                content=fts_result.content,
+                user_id=fts_result.metadata.get("user_id", ""),
+                category=MemoryCategory(fts_result.metadata.get("category", "fact")),
+            )
+            results.append(
+                TextSearchResult(
+                    memory=memory,
+                    score=fts_result.score,
+                    rank=rank,
+                )
+            )
+        return results
+
+    async def update_content(self, memory_id: str, content: str) -> bool:
+        """Update the indexed content for a memory (protocol-compliant).
+
+        Args:
+            memory_id: The unique identifier of the memory.
+            content: The new content to index.
+
+        Returns:
+            True if updated, False if memory not found in index.
+        """
+        # Check if exists first
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "SELECT user_id, session_id, category FROM memory_fts WHERE memory_id = ?",
+                (memory_id,),
+            )
+            row = cursor.fetchone()
+            if row is None:
+                return False
+
+            # Re-index with new content
+            metadata = {
+                "user_id": row["user_id"],
+                "session_id": row["session_id"],
+                "category": row["category"],
+            }
+            self.index(memory_id, content, metadata)
+            return True

headroom/memory/adapters/hnsw.py

@@ -0,0 +1,803 @@
+"""HNSW vector index for Headroom Memory using hnswlib.
+
+Provides fast approximate nearest neighbor search with cosine similarity
+for semantic memory retrieval. Supports filtering by user_id, session_id,
+agent_id, category, and entity references.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from threading import Lock
+from typing import TYPE_CHECKING, Any
+
+import hnswlib
+import numpy as np
+
+from ..models import Memory, MemoryCategory, ScopeLevel
+from ..ports import VectorFilter, VectorSearchResult
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class IndexedMemoryMetadata:
+    """Metadata stored alongside vectors for post-filtering.
+
+    Stores all filterable fields from Memory to enable
+    post-retrieval filtering without accessing the main store.
+    """
+
+    memory_id: str
+    user_id: str
+    session_id: str | None
+    agent_id: str | None
+    category: str  # Stored as string value
+    valid_until: datetime | None
+    entity_refs: list[str]
+    content: str  # For reconstructing Memory in search results
+    created_at: datetime
+    importance: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for persistence."""
+        return {
+            "memory_id": self.memory_id,
+            "user_id": self.user_id,
+            "session_id": self.session_id,
+            "agent_id": self.agent_id,
+            "category": self.category,
+            "valid_until": self.valid_until.isoformat() if self.valid_until else None,
+            "entity_refs": self.entity_refs,
+            "content": self.content,
+            "created_at": self.created_at.isoformat(),
+            "importance": self.importance,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> IndexedMemoryMetadata:
+        """Deserialize from dictionary."""
+        return cls(
+            memory_id=data["memory_id"],
+            user_id=data["user_id"],
+            session_id=data.get("session_id"),
+            agent_id=data.get("agent_id"),
+            category=data["category"],
+            valid_until=(
+                datetime.fromisoformat(data["valid_until"]) if data.get("valid_until") else None
+            ),
+            entity_refs=data.get("entity_refs", []),
+            content=data["content"],
+            created_at=datetime.fromisoformat(data["created_at"]),
+            importance=data.get("importance", 0.5),
+        )
+
+    @classmethod
+    def from_memory(cls, memory: Memory) -> IndexedMemoryMetadata:
+        """Create metadata from a Memory object."""
+        category_value = (
+            memory.category.value
+            if isinstance(memory.category, MemoryCategory)
+            else memory.category
+        )
+        return cls(
+            memory_id=memory.id,
+            user_id=memory.user_id,
+            session_id=memory.session_id,
+            agent_id=memory.agent_id,
+            category=category_value,
+            valid_until=memory.valid_until,
+            entity_refs=memory.entity_refs.copy(),
+            content=memory.content,
+            created_at=memory.created_at,
+            importance=memory.importance,
+        )
+
+    def to_memory(self, embedding: np.ndarray | None = None) -> Memory:
+        """Reconstruct a basic Memory object from metadata.
+
+        Note: This creates a partial Memory with only indexed fields.
+        For full Memory objects, retrieve from the MemoryStore.
+        """
+        return Memory(
+            id=self.memory_id,
+            content=self.content,
+            user_id=self.user_id,
+            session_id=self.session_id,
+            agent_id=self.agent_id,
+            category=MemoryCategory(self.category),
+            valid_until=self.valid_until,
+            entity_refs=self.entity_refs.copy(),
+            created_at=self.created_at,
+            importance=self.importance,
+            embedding=embedding,
+        )
+
+
+class HNSWVectorIndex:
+    """HNSW-based vector index using hnswlib.
+
+    Features:
+    - Fast approximate nearest neighbor search with cosine similarity
+    - Configurable HNSW parameters (ef_construction, M, ef_search)
+    - Post-filtering by user_id, session_id, agent_id, category, entity_refs
+    - Bidirectional ID mapping (string memory_id <-> integer hnsw_id)
+    - Persistence support with save_index/load_index
+    - Thread-safe operations with Lock
+    - Optional auto-save on index modifications
+
+    Usage:
+        index = HNSWVectorIndex(dimension=384)
+        await index.index(memory_with_embedding)
+        results = await index.search(VectorFilter(
+            query_vector=query_embedding,
+            top_k=10,
+            user_id="alice"
+        ))
+
+    HNSW Parameters:
+    - ef_construction: Size of dynamic candidate list during index construction.
+      Higher values give better quality but slower construction. Default: 200
+    - M: Number of bi-directional links per element. Higher values give
+      better recall but use more memory. Default: 16
+    - ef_search: Size of dynamic candidate list during search. Higher values
+      give better recall but slower search. Default: 50
+    """
+
+    def __init__(
+        self,
+        dimension: int = 384,
+        max_elements: int = 100000,
+        ef_construction: int = 200,
+        m: int = 16,
+        ef_search: int = 50,
+        auto_save: bool = False,
+        save_path: str | Path | None = None,
+    ) -> None:
+        """Initialize the HNSW vector index.
+
+        Args:
+            dimension: Embedding dimension. Default 384 for MiniLM.
+            max_elements: Maximum number of elements the index can hold.
+                         Can be resized later with resize_index().
+            ef_construction: HNSW construction parameter. Higher = better quality,
+                           slower construction. Default: 200
+            m: HNSW links per element. Higher = better recall, more memory.
+               Default: 16
+            ef_search: HNSW search parameter. Higher = better recall, slower
+                      search. Default: 50
+            auto_save: If True and save_path is set, automatically save
+                      index after modifications.
+            save_path: Path for auto-save operations. Required if auto_save=True.
+
+        Raises:
+            ValueError: If auto_save is True but save_path is not provided.
+        """
+        if auto_save and save_path is None:
+            raise ValueError("save_path must be provided when auto_save is True")
+
+        self._dimension = dimension
+        self._max_elements = max_elements
+        self._ef_construction = ef_construction
+        self._m = m
+        self._ef_search = ef_search
+        self._auto_save = auto_save
+        self._save_path = Path(save_path) if save_path else None
+
+        # Initialize HNSW index with cosine similarity
+        # hnswlib uses 'cosine' space which internally normalizes vectors
+        self._index = hnswlib.Index(space="cosine", dim=dimension)
+        self._index.init_index(
+            max_elements=max_elements,
+            ef_construction=ef_construction,
+            M=m,
+        )
+        self._index.set_ef(ef_search)
+
+        # ID mappings: string memory_id <-> integer hnsw_id
+        self._memory_to_hnsw: dict[str, int] = {}
+        self._hnsw_to_memory: dict[int, str] = {}
+        self._next_hnsw_id: int = 0
+
+        # Metadata storage for filtering
+        self._metadata: dict[str, IndexedMemoryMetadata] = {}
+
+        # Embedding storage for retrieval
+        self._embeddings: dict[str, np.ndarray] = {}
+
+        # Thread safety
+        self._lock = Lock()
+
+    @property
+    def dimension(self) -> int:
+        """Return the embedding dimension this index expects."""
+        return self._dimension
+
+    @property
+    def size(self) -> int:
+        """Return the number of vectors currently indexed."""
+        with self._lock:
+            return len(self._memory_to_hnsw)
+
+    async def index(self, memory: Memory) -> None:
+        """Index a memory's embedding for similarity search.
+
+        The memory must have an embedding set.
+
+        Args:
+            memory: The memory to index.
+
+        Raises:
+            ValueError: If the memory has no embedding or wrong dimension.
+        """
+        if memory.embedding is None:
+            raise ValueError(f"Memory {memory.id} has no embedding")
+
+        embedding = np.asarray(memory.embedding, dtype=np.float32)
+        if embedding.shape[0] != self._dimension:
+            raise ValueError(
+                f"Embedding dimension {embedding.shape[0]} does not match "
+                f"index dimension {self._dimension}"
+            )
+
+        with self._lock:
+            # Check if already indexed - update if so
+            if memory.id in self._memory_to_hnsw:
+                await self._update_embedding_internal(memory.id, embedding)
+                # Update metadata
+                self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
+            else:
+                # Resize if needed
+                if self._next_hnsw_id >= self._max_elements:
+                    self._resize_index(self._max_elements * 2)
+
+                # Add to HNSW index
+                hnsw_id = self._next_hnsw_id
+                self._index.add_items(
+                    embedding.reshape(1, -1),
+                    np.array([hnsw_id]),
+                )
+
+                # Update mappings
+                self._memory_to_hnsw[memory.id] = hnsw_id
+                self._hnsw_to_memory[hnsw_id] = memory.id
+                self._next_hnsw_id += 1
+
+                # Store metadata and embedding
+                self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
+                self._embeddings[memory.id] = embedding.copy()
+
+        if self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+    async def index_batch(self, memories: list[Memory]) -> int:
+        """Index multiple memories' embeddings.
+
+        Memories without embeddings are skipped.
+
+        Args:
+            memories: List of memories to index.
+
+        Returns:
+            Number of memories actually indexed.
+        """
+        # Filter memories with valid embeddings
+        valid_memories: list[tuple[Memory, np.ndarray]] = []
+        for memory in memories:
+            if memory.embedding is not None:
+                embedding = np.asarray(memory.embedding, dtype=np.float32)
+                if embedding.shape[0] == self._dimension:
+                    valid_memories.append((memory, embedding))
+
+        if not valid_memories:
+            return 0
+
+        with self._lock:
+            # Separate new memories from updates
+            new_memories: list[tuple[Memory, np.ndarray, int]] = []
+            update_memories: list[tuple[Memory, np.ndarray]] = []
+
+            for memory, embedding in valid_memories:
+                if memory.id in self._memory_to_hnsw:
+                    update_memories.append((memory, embedding))
+                else:
+                    hnsw_id = self._next_hnsw_id
+                    new_memories.append((memory, embedding, hnsw_id))
+                    self._next_hnsw_id += 1
+
+            # Resize if needed
+            required_capacity = len(self._memory_to_hnsw) + len(new_memories)
+            if required_capacity > self._max_elements:
+                new_max = max(self._max_elements * 2, required_capacity + 1000)
+                self._resize_index(new_max)
+
+            # Batch add new memories
+            if new_memories:
+                embeddings_array = np.vstack([emb for _, emb, _ in new_memories]).astype(np.float32)
+                ids_array = np.array([hid for _, _, hid in new_memories])
+
+                self._index.add_items(embeddings_array, ids_array)
+
+                # Update mappings and metadata
+                for memory, embedding, hnsw_id in new_memories:
+                    self._memory_to_hnsw[memory.id] = hnsw_id
+                    self._hnsw_to_memory[hnsw_id] = memory.id
+                    self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
+                    self._embeddings[memory.id] = embedding.copy()
+
+            # Handle updates (hnswlib doesn't support true updates, so we track separately)
+            for memory, embedding in update_memories:
+                self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
+                self._embeddings[memory.id] = embedding.copy()
+                # Note: HNSW embedding stays unchanged unless we remove and re-add
+
+        if self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+        return len(valid_memories)
+
+    async def remove(self, memory_id: str) -> bool:
+        """Remove a memory from the vector index.
+
+        Note: hnswlib doesn't support true deletion. We mark the item as deleted
+        and exclude it from results. The space is reclaimed on next save/load.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        with self._lock:
+            if memory_id not in self._memory_to_hnsw:
+                return False
+
+            hnsw_id = self._memory_to_hnsw[memory_id]
+
+            # Mark as deleted in HNSW index
+            self._index.mark_deleted(hnsw_id)
+
+            # Remove from our mappings
+            del self._memory_to_hnsw[memory_id]
+            del self._hnsw_to_memory[hnsw_id]
+
+            # Remove metadata and embedding
+            if memory_id in self._metadata:
+                del self._metadata[memory_id]
+            if memory_id in self._embeddings:
+                del self._embeddings[memory_id]
+
+        if self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+        return True
+
+    async def remove_batch(self, memory_ids: list[str]) -> int:
+        """Remove multiple memories from the vector index.
+
+        Args:
+            memory_ids: List of memory IDs to remove.
+
+        Returns:
+            Number of memories actually removed.
+        """
+        removed_count = 0
+
+        with self._lock:
+            for memory_id in memory_ids:
+                if memory_id not in self._memory_to_hnsw:
+                    continue
+
+                hnsw_id = self._memory_to_hnsw[memory_id]
+
+                # Mark as deleted in HNSW index
+                self._index.mark_deleted(hnsw_id)
+
+                # Remove from our mappings
+                del self._memory_to_hnsw[memory_id]
+                del self._hnsw_to_memory[hnsw_id]
+
+                # Remove metadata and embedding
+                if memory_id in self._metadata:
+                    del self._metadata[memory_id]
+                if memory_id in self._embeddings:
+                    del self._embeddings[memory_id]
+
+                removed_count += 1
+
+        if removed_count > 0 and self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+        return removed_count
+
+    async def search(self, filter: VectorFilter) -> list[VectorSearchResult]:
+        """Search for similar memories using vector similarity.
+
+        Args:
+            filter: Vector search filter with query and constraints.
+
+        Returns:
+            List of search results sorted by similarity (descending).
+
+        Raises:
+            ValueError: If neither query_vector nor query_text is provided,
+                       or if query_text is provided (embedding must be done externally).
+        """
+        if filter.query_vector is None:
+            if filter.query_text is not None:
+                raise ValueError(
+                    "query_text provided but HNSWVectorIndex does not embed text. "
+                    "Provide query_vector directly or use an Embedder first."
+                )
+            raise ValueError("Either query_vector or query_text must be provided")
+
+        query_vector = np.asarray(filter.query_vector, dtype=np.float32)
+        if query_vector.shape[0] != self._dimension:
+            raise ValueError(
+                f"Query vector dimension {query_vector.shape[0]} does not match "
+                f"index dimension {self._dimension}"
+            )
+
+        with self._lock:
+            # NOTE: Use len() directly, not self.size - Lock is not reentrant!
+            current_size = len(self._memory_to_hnsw)
+            if current_size == 0:
+                return []
+
+            # Search with more results than needed to account for filtering
+            # Retrieve extra candidates to improve recall after filtering
+            k_with_buffer = min(
+                filter.top_k * 10,  # Get 10x candidates for filtering
+                current_size,  # But not more than we have
+            )
+
+            # Query HNSW index
+            # Returns (labels, distances) where labels are hnsw_ids
+            labels, distances = self._index.knn_query(
+                query_vector.reshape(1, -1),
+                k=k_with_buffer,
+            )
+
+            # Convert distances to similarities
+            # hnswlib with 'cosine' space returns 1 - cosine_similarity
+            # So similarity = 1 - distance
+            similarities = 1.0 - distances[0]
+
+            # Build results with post-filtering
+            results: list[VectorSearchResult] = []
+
+            for hnsw_id, similarity in zip(labels[0], similarities):
+                # Skip if not in our mapping (deleted)
+                if hnsw_id not in self._hnsw_to_memory:
+                    continue
+
+                memory_id = self._hnsw_to_memory[hnsw_id]
+
+                # Skip if below minimum similarity
+                if similarity < filter.min_similarity:
+                    continue
+
+                # Get metadata for filtering
+                metadata = self._metadata.get(memory_id)
+                if metadata is None:
+                    continue
+
+                # Apply filters
+                if not self._passes_filter(metadata, filter):
+                    continue
+
+                # Get stored embedding
+                embedding = self._embeddings.get(memory_id)
+
+                # Create Memory from metadata
+                memory = metadata.to_memory(embedding=embedding)
+
+                results.append(
+                    VectorSearchResult(
+                        memory=memory,
+                        similarity=float(similarity),
+                        rank=0,  # Will be set after sorting
+                    )
+                )
+
+                # Stop if we have enough results
+                if len(results) >= filter.top_k:
+                    break
+
+            # Sort by similarity (descending) and assign ranks
+            results.sort(key=lambda r: r.similarity, reverse=True)
+            for i, result in enumerate(results):
+                result.rank = i + 1
+
+            return results[: filter.top_k]
+
+    def _passes_filter(
+        self,
+        metadata: IndexedMemoryMetadata,
+        filter: VectorFilter,
+    ) -> bool:
+        """Check if metadata passes all filter constraints.
+
+        Args:
+            metadata: The indexed memory metadata.
+            filter: The vector filter with constraints.
+
+        Returns:
+            True if all filter constraints pass, False otherwise.
+        """
+        # User ID filter
+        if filter.user_id is not None and metadata.user_id != filter.user_id:
+            return False
+
+        # Session ID filter
+        if filter.session_id is not None and metadata.session_id != filter.session_id:
+            return False
+
+        # Agent ID filter
+        if filter.agent_id is not None and metadata.agent_id != filter.agent_id:
+            return False
+
+        # Scope level filter
+        if filter.scope_levels is not None:
+            # Determine the memory's scope level
+            if metadata.agent_id is not None:
+                memory_scope = ScopeLevel.AGENT
+            elif metadata.session_id is not None:
+                memory_scope = ScopeLevel.SESSION
+            else:
+                memory_scope = ScopeLevel.USER
+
+            if memory_scope not in filter.scope_levels:
+                return False
+
+        # Category filter
+        if filter.categories is not None:
+            category_values = []
+            for cat in filter.categories:
+                if isinstance(cat, MemoryCategory):
+                    category_values.append(cat.value)
+                else:
+                    category_values.append(cat)
+
+            if metadata.category not in category_values:
+                return False
+
+        # Temporal filter - valid_at
+        if filter.valid_at is not None:
+            # Memory must be valid at the specified time
+            # If valid_until is None, memory is current (always valid after creation)
+            # If valid_until is set, memory must have been valid at that time
+            if metadata.valid_until is not None:
+                if filter.valid_at > metadata.valid_until:
+                    return False
+
+        # Superseded filter
+        if not filter.include_superseded:
+            # Exclude superseded memories (those with valid_until set)
+            if metadata.valid_until is not None:
+                return False
+
+        # Entity refs filter - any match
+        if filter.entity_refs is not None and len(filter.entity_refs) > 0:
+            if not any(ref in metadata.entity_refs for ref in filter.entity_refs):
+                return False
+
+        # Metadata filters (custom key-value pairs)
+        # Note: We don't store custom metadata in IndexedMemoryMetadata
+        # This would require extending the metadata storage
+
+        return True
+
+    async def update_embedding(self, memory_id: str, embedding: np.ndarray) -> bool:
+        """Update the embedding for an indexed memory.
+
+        Note: hnswlib doesn't support in-place updates. This stores the new
+        embedding but the HNSW graph uses the original. For full update,
+        remove and re-index the memory.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+            embedding: The new embedding vector.
+
+        Returns:
+            True if updated, False if memory not found in index.
+        """
+        embedding = np.asarray(embedding, dtype=np.float32)
+        if embedding.shape[0] != self._dimension:
+            raise ValueError(
+                f"Embedding dimension {embedding.shape[0]} does not match "
+                f"index dimension {self._dimension}"
+            )
+
+        with self._lock:
+            result = await self._update_embedding_internal(memory_id, embedding)
+
+        if result and self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+        return result
+
+    async def _update_embedding_internal(self, memory_id: str, embedding: np.ndarray) -> bool:
+        """Internal embedding update without lock (caller must hold lock).
+
+        hnswlib doesn't support true in-place updates, so we:
+        1. Store the new embedding in our local cache
+        2. The HNSW index continues to use the old embedding for search
+
+        For a true update, the caller should remove and re-index.
+        """
+        if memory_id not in self._memory_to_hnsw:
+            return False
+
+        self._embeddings[memory_id] = embedding.copy()
+        return True
+
+    def _resize_index(self, new_max_elements: int) -> None:
+        """Resize the HNSW index to accommodate more elements.
+
+        Must be called with lock held.
+
+        Args:
+            new_max_elements: New maximum capacity.
+        """
+        self._index.resize_index(new_max_elements)
+        self._max_elements = new_max_elements
+
+    def save_index(self, path: str | Path) -> None:
+        """Save the index to disk.
+
+        Saves both the HNSW index and all metadata/mappings.
+
+        Args:
+            path: Base path for the saved files. Will create:
+                  - {path}.hnsw - The HNSW index
+                  - {path}.meta - Metadata and mappings (pickled)
+        """
+        path = Path(path)
+
+        with self._lock:
+            # Save HNSW index
+            hnsw_path = path.with_suffix(".hnsw")
+            self._index.save_index(str(hnsw_path))
+
+            # Save metadata, mappings, and embeddings
+            meta_path = path.with_suffix(".meta")
+            meta_data = {
+                "dimension": self._dimension,
+                "max_elements": self._max_elements,
+                "ef_construction": self._ef_construction,
+                "m": self._m,
+                "ef_search": self._ef_search,
+                "memory_to_hnsw": self._memory_to_hnsw,
+                "hnsw_to_memory": self._hnsw_to_memory,
+                "next_hnsw_id": self._next_hnsw_id,
+                "metadata": {mid: meta.to_dict() for mid, meta in self._metadata.items()},
+                "embeddings": {mid: emb.tolist() for mid, emb in self._embeddings.items()},
+            }
+
+            with open(meta_path, "w") as f:
+                json.dump(meta_data, f)
+
+    def load_index(self, path: str | Path) -> None:
+        """Load the index from disk.
+
+        Loads both the HNSW index and all metadata/mappings.
+
+        Args:
+            path: Base path for the saved files.
+
+        Raises:
+            FileNotFoundError: If the index files don't exist.
+            ValueError: If the saved dimension doesn't match.
+        """
+        path = Path(path)
+        hnsw_path = path.with_suffix(".hnsw")
+        meta_path = path.with_suffix(".meta")
+
+        if not hnsw_path.exists():
+            raise FileNotFoundError(f"HNSW index not found: {hnsw_path}")
+        if not meta_path.exists():
+            raise FileNotFoundError(f"Metadata file not found: {meta_path}")
+
+        # Load metadata first to get parameters
+        with open(meta_path) as f:
+            meta_data = json.load(f)
+
+        # Verify dimension matches
+        saved_dimension = meta_data["dimension"]
+        if saved_dimension != self._dimension:
+            raise ValueError(
+                f"Saved index dimension {saved_dimension} does not match "
+                f"current dimension {self._dimension}"
+            )
+
+        with self._lock:
+            # Update parameters
+            self._max_elements = meta_data["max_elements"]
+            self._ef_construction = meta_data["ef_construction"]
+            self._m = meta_data["m"]
+            self._ef_search = meta_data["ef_search"]
+
+            # Create new index and load from file
+            self._index = hnswlib.Index(space="cosine", dim=self._dimension)
+            self._index.load_index(
+                str(hnsw_path),
+                max_elements=self._max_elements,
+            )
+            self._index.set_ef(self._ef_search)
+
+            # Restore mappings
+            # JSON converts int keys to strings, so we need to convert back
+            self._memory_to_hnsw = meta_data["memory_to_hnsw"]
+            self._hnsw_to_memory = {int(k): v for k, v in meta_data["hnsw_to_memory"].items()}
+            self._next_hnsw_id = meta_data["next_hnsw_id"]
+
+            # Restore metadata
+            self._metadata = {
+                mid: IndexedMemoryMetadata.from_dict(meta_dict)
+                for mid, meta_dict in meta_data["metadata"].items()
+            }
+
+            # Restore embeddings
+            self._embeddings = {
+                mid: np.array(emb, dtype=np.float32) for mid, emb in meta_data["embeddings"].items()
+            }
+
+    def clear(self) -> None:
+        """Clear all entries from the index."""
+        with self._lock:
+            # Reinitialize the index
+            self._index = hnswlib.Index(space="cosine", dim=self._dimension)
+            self._index.init_index(
+                max_elements=self._max_elements,
+                ef_construction=self._ef_construction,
+                M=self._m,
+            )
+            self._index.set_ef(self._ef_search)
+
+            # Clear all mappings and metadata
+            self._memory_to_hnsw.clear()
+            self._hnsw_to_memory.clear()
+            self._next_hnsw_id = 0
+            self._metadata.clear()
+            self._embeddings.clear()
+
+        if self._auto_save and self._save_path:
+            self.save_index(self._save_path)
+
+    def stats(self) -> dict[str, Any]:
+        """Get index statistics.
+
+        Returns:
+            Dictionary with index metrics.
+        """
+        with self._lock:
+            return {
+                "size": len(self._memory_to_hnsw),
+                "dimension": self._dimension,
+                "max_elements": self._max_elements,
+                "ef_construction": self._ef_construction,
+                "m": self._m,
+                "ef_search": self._ef_search,
+                "utilization": (
+                    (len(self._memory_to_hnsw) / self._max_elements) * 100
+                    if self._max_elements > 0
+                    else 0.0
+                ),
+            }
+
+    def set_ef_search(self, ef_search: int) -> None:
+        """Update the ef_search parameter for query time.
+
+        Higher values give better recall but slower search.
+
+        Args:
+            ef_search: New ef_search value.
+        """
+        with self._lock:
+            self._ef_search = ef_search
+            self._index.set_ef(ef_search)

headroom/memory/adapters/sqlite.py

@@ -0,0 +1,752 @@
+"""SQLite memory store for Headroom's hierarchical memory system.
+
+Provides persistent storage for Memory objects with full support for:
+- Hierarchical scope filtering (user/session/agent/turn)
+- Temporal versioning with supersession chains
+- Point-in-time queries
+- Efficient batch operations
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ..models import Memory, MemoryCategory, ScopeLevel
+from ..ports import MemoryFilter
+
+
+class SQLiteMemoryStore:
+    """SQLite-based memory store implementing the MemoryStore protocol.
+
+    Features:
+    - Full CRUD operations with batch support
+    - Hierarchical scope filtering (user -> session -> agent -> turn)
+    - Temporal versioning with supersession chains
+    - Point-in-time queries via valid_at filter
+    - Thread-safe: connection-per-request pattern
+
+    Usage:
+        store = SQLiteMemoryStore("./memories.db")
+        await store.save(memory)
+        memories = await store.query(MemoryFilter(user_id="alice"))
+
+    Schema:
+        The memories table stores all Memory fields with appropriate indexes
+        for efficient querying by scope, category, importance, and time.
+    """
+
+    def __init__(self, db_path: str | Path = "headroom_memory.db") -> None:
+        """Initialize the SQLite memory store.
+
+        Args:
+            db_path: Path to SQLite database file. Created if it doesn't exist.
+        """
+        self.db_path = Path(db_path)
+        self._init_db()
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a new database connection (thread-safe pattern).
+
+        Returns:
+            A new SQLite connection with row factory configured.
+        """
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        """Initialize the database schema with indexes."""
+        with self._get_conn() as conn:
+            # Create memories table
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id TEXT PRIMARY KEY,
+                    content TEXT NOT NULL,
+
+                    -- Hierarchical scoping
+                    user_id TEXT NOT NULL,
+                    session_id TEXT,
+                    agent_id TEXT,
+                    turn_id TEXT,
+
+                    -- Temporal
+                    created_at TEXT NOT NULL,
+                    valid_from TEXT NOT NULL,
+                    valid_until TEXT,
+
+                    -- Classification
+                    category TEXT NOT NULL,
+                    importance REAL NOT NULL DEFAULT 0.5,
+
+                    -- Lineage
+                    supersedes TEXT,
+                    superseded_by TEXT,
+                    promoted_from TEXT,
+                    promotion_chain TEXT NOT NULL DEFAULT '[]',
+
+                    -- Access tracking
+                    access_count INTEGER NOT NULL DEFAULT 0,
+                    last_accessed TEXT,
+
+                    -- Entity references (JSON array)
+                    entity_refs TEXT NOT NULL DEFAULT '[]',
+
+                    -- Embedding (BLOB for numpy array)
+                    embedding BLOB,
+
+                    -- Metadata (JSON object)
+                    metadata TEXT NOT NULL DEFAULT '{}'
+                )
+            """)
+
+            # Create indexes for efficient querying
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_user_id ON memories(user_id)")
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_session_id ON memories(session_id)"
+            )
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_agent_id ON memories(agent_id)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_turn_id ON memories(turn_id)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category)")
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance)"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at)"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_valid_until ON memories(valid_until)"
+            )
+
+            # Composite index for common scope queries
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_memories_scope
+                ON memories(user_id, session_id, agent_id, turn_id)
+            """)
+
+            # Index for supersession chain traversal
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_supersedes ON memories(supersedes)"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_superseded_by ON memories(superseded_by)"
+            )
+
+            conn.commit()
+
+    def _serialize_embedding(self, embedding: np.ndarray | None) -> bytes | None:
+        """Serialize numpy array to bytes for BLOB storage."""
+        if embedding is None:
+            return None
+        return embedding.astype(np.float32).tobytes()
+
+    def _deserialize_embedding(
+        self, data: bytes | None, dim: int | None = None
+    ) -> np.ndarray | None:
+        """Deserialize bytes back to numpy array."""
+        if data is None:
+            return None
+        arr = np.frombuffer(data, dtype=np.float32)
+        return arr
+
+    def _memory_to_row(self, memory: Memory) -> dict[str, Any]:
+        """Convert Memory object to row dict for insertion."""
+        return {
+            "id": memory.id,
+            "content": memory.content,
+            "user_id": memory.user_id,
+            "session_id": memory.session_id,
+            "agent_id": memory.agent_id,
+            "turn_id": memory.turn_id,
+            "created_at": memory.created_at.isoformat(),
+            "valid_from": memory.valid_from.isoformat(),
+            "valid_until": memory.valid_until.isoformat() if memory.valid_until else None,
+            "category": memory.category.value,
+            "importance": memory.importance,
+            "supersedes": memory.supersedes,
+            "superseded_by": memory.superseded_by,
+            "promoted_from": memory.promoted_from,
+            "promotion_chain": json.dumps(memory.promotion_chain),
+            "access_count": memory.access_count,
+            "last_accessed": memory.last_accessed.isoformat() if memory.last_accessed else None,
+            "entity_refs": json.dumps(memory.entity_refs),
+            "embedding": self._serialize_embedding(memory.embedding),
+            "metadata": json.dumps(memory.metadata),
+        }
+
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory:
+        """Convert database row to Memory object."""
+        return Memory(
+            id=row["id"],
+            content=row["content"],
+            user_id=row["user_id"],
+            session_id=row["session_id"],
+            agent_id=row["agent_id"],
+            turn_id=row["turn_id"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            valid_from=datetime.fromisoformat(row["valid_from"]),
+            valid_until=datetime.fromisoformat(row["valid_until"]) if row["valid_until"] else None,
+            category=MemoryCategory(row["category"]),
+            importance=row["importance"],
+            supersedes=row["supersedes"],
+            superseded_by=row["superseded_by"],
+            promoted_from=row["promoted_from"],
+            promotion_chain=json.loads(row["promotion_chain"]),
+            access_count=row["access_count"],
+            last_accessed=datetime.fromisoformat(row["last_accessed"])
+            if row["last_accessed"]
+            else None,
+            entity_refs=json.loads(row["entity_refs"]),
+            embedding=self._deserialize_embedding(row["embedding"]),
+            metadata=json.loads(row["metadata"]),
+        )
+
+    async def save(self, memory: Memory) -> None:
+        """Save or update a memory.
+
+        If a memory with the same ID exists, it will be updated.
+
+        Args:
+            memory: The memory to save.
+        """
+        row = self._memory_to_row(memory)
+
+        with self._get_conn() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO memories (
+                    id, content, user_id, session_id, agent_id, turn_id,
+                    created_at, valid_from, valid_until,
+                    category, importance,
+                    supersedes, superseded_by, promoted_from, promotion_chain,
+                    access_count, last_accessed,
+                    entity_refs, embedding, metadata
+                ) VALUES (
+                    :id, :content, :user_id, :session_id, :agent_id, :turn_id,
+                    :created_at, :valid_from, :valid_until,
+                    :category, :importance,
+                    :supersedes, :superseded_by, :promoted_from, :promotion_chain,
+                    :access_count, :last_accessed,
+                    :entity_refs, :embedding, :metadata
+                )
+                """,
+                row,
+            )
+            conn.commit()
+
+    async def save_batch(self, memories: list[Memory]) -> None:
+        """Save multiple memories in a single transaction.
+
+        Args:
+            memories: List of memories to save.
+        """
+        if not memories:
+            return
+
+        rows = [self._memory_to_row(m) for m in memories]
+
+        with self._get_conn() as conn:
+            conn.executemany(
+                """
+                INSERT OR REPLACE INTO memories (
+                    id, content, user_id, session_id, agent_id, turn_id,
+                    created_at, valid_from, valid_until,
+                    category, importance,
+                    supersedes, superseded_by, promoted_from, promotion_chain,
+                    access_count, last_accessed,
+                    entity_refs, embedding, metadata
+                ) VALUES (
+                    :id, :content, :user_id, :session_id, :agent_id, :turn_id,
+                    :created_at, :valid_from, :valid_until,
+                    :category, :importance,
+                    :supersedes, :superseded_by, :promoted_from, :promotion_chain,
+                    :access_count, :last_accessed,
+                    :entity_refs, :embedding, :metadata
+                )
+                """,
+                rows,
+            )
+            conn.commit()
+
+    async def get(self, memory_id: str) -> Memory | None:
+        """Retrieve a memory by ID.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            The memory if found, None otherwise.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "SELECT * FROM memories WHERE id = ?",
+                (memory_id,),
+            )
+            row = cursor.fetchone()
+
+            if row is None:
+                return None
+
+            return self._row_to_memory(row)
+
+    async def get_batch(self, memory_ids: list[str]) -> list[Memory]:
+        """Retrieve multiple memories by ID.
+
+        Args:
+            memory_ids: List of memory IDs to retrieve.
+
+        Returns:
+            List of found memories (may be shorter than input if some not found).
+        """
+        if not memory_ids:
+            return []
+
+        placeholders = ", ".join("?" * len(memory_ids))
+
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                f"SELECT * FROM memories WHERE id IN ({placeholders})",
+                memory_ids,
+            )
+
+            return [self._row_to_memory(row) for row in cursor]
+
+    async def delete(self, memory_id: str) -> bool:
+        """Delete a memory by ID.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if the memory was deleted, False if not found.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "DELETE FROM memories WHERE id = ?",
+                (memory_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    async def delete_batch(self, memory_ids: list[str]) -> int:
+        """Delete multiple memories by ID.
+
+        Args:
+            memory_ids: List of memory IDs to delete.
+
+        Returns:
+            Number of memories actually deleted.
+        """
+        if not memory_ids:
+            return 0
+
+        placeholders = ", ".join("?" * len(memory_ids))
+
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM memories WHERE id IN ({placeholders})",
+                memory_ids,
+            )
+            conn.commit()
+            return cursor.rowcount
+
+    def _build_query_conditions(self, filter: MemoryFilter) -> tuple[list[str], list[Any]]:
+        """Build WHERE clause conditions from a MemoryFilter.
+
+        Returns:
+            Tuple of (conditions list, params list).
+        """
+        conditions: list[str] = []
+        params: list[Any] = []
+
+        # Hierarchical scope filtering
+        if filter.user_id is not None:
+            conditions.append("user_id = ?")
+            params.append(filter.user_id)
+
+            # Hierarchical filtering: when filtering by user_id only,
+            # return USER-level and below (all that user's memories)
+            # This is implicit - we just filter by user_id
+
+            if filter.session_id is not None:
+                conditions.append("session_id = ?")
+                params.append(filter.session_id)
+
+                if filter.agent_id is not None:
+                    conditions.append("agent_id = ?")
+                    params.append(filter.agent_id)
+
+                    if filter.turn_id is not None:
+                        conditions.append("turn_id = ?")
+                        params.append(filter.turn_id)
+            elif filter.agent_id is not None:
+                # Agent without session - unusual but supported
+                conditions.append("agent_id = ?")
+                params.append(filter.agent_id)
+            elif filter.turn_id is not None:
+                # Turn without session/agent - unusual but supported
+                conditions.append("turn_id = ?")
+                params.append(filter.turn_id)
+        elif filter.session_id is not None:
+            # Session without user - filter by session only
+            conditions.append("session_id = ?")
+            params.append(filter.session_id)
+        elif filter.agent_id is not None:
+            # Agent without user/session
+            conditions.append("agent_id = ?")
+            params.append(filter.agent_id)
+        elif filter.turn_id is not None:
+            # Turn only
+            conditions.append("turn_id = ?")
+            params.append(filter.turn_id)
+
+        # Explicit scope level filtering
+        if filter.scope_levels is not None and len(filter.scope_levels) > 0:
+            scope_conditions = []
+            for level in filter.scope_levels:
+                if level == ScopeLevel.USER:
+                    # USER level: no session/agent/turn
+                    scope_conditions.append(
+                        "(session_id IS NULL AND agent_id IS NULL AND turn_id IS NULL)"
+                    )
+                elif level == ScopeLevel.SESSION:
+                    # SESSION level: has session, no agent/turn
+                    scope_conditions.append(
+                        "(session_id IS NOT NULL AND agent_id IS NULL AND turn_id IS NULL)"
+                    )
+                elif level == ScopeLevel.AGENT:
+                    # AGENT level: has agent, no turn
+                    scope_conditions.append("(agent_id IS NOT NULL AND turn_id IS NULL)")
+                elif level == ScopeLevel.TURN:
+                    # TURN level: has turn
+                    scope_conditions.append("(turn_id IS NOT NULL)")
+
+            if scope_conditions:
+                conditions.append(f"({' OR '.join(scope_conditions)})")
+
+        # Category filtering
+        if filter.categories is not None and len(filter.categories) > 0:
+            category_values = [
+                c.value if isinstance(c, MemoryCategory) else c for c in filter.categories
+            ]
+            placeholders = ", ".join("?" * len(category_values))
+            conditions.append(f"category IN ({placeholders})")
+            params.extend(category_values)
+
+        # Temporal filtering
+        if filter.created_after is not None:
+            conditions.append("created_at >= ?")
+            params.append(filter.created_after.isoformat())
+
+        if filter.created_before is not None:
+            conditions.append("created_at <= ?")
+            params.append(filter.created_before.isoformat())
+
+        # Point-in-time query
+        if filter.valid_at is not None:
+            valid_at_str = filter.valid_at.isoformat()
+            conditions.append("valid_from <= ?")
+            params.append(valid_at_str)
+            conditions.append("(valid_until IS NULL OR valid_until > ?)")
+            params.append(valid_at_str)
+
+        # Superseded filtering
+        if not filter.include_superseded:
+            # Default: only return current memories (not superseded)
+            conditions.append("valid_until IS NULL")
+
+        # Importance filtering
+        if filter.min_importance is not None:
+            conditions.append("importance >= ?")
+            params.append(filter.min_importance)
+
+        if filter.max_importance is not None:
+            conditions.append("importance <= ?")
+            params.append(filter.max_importance)
+
+        # Entity reference filtering (any of the specified entities)
+        if filter.entity_refs is not None and len(filter.entity_refs) > 0:
+            entity_conditions = []
+            for entity_ref in filter.entity_refs:
+                # Use JSON contains check
+                entity_conditions.append("entity_refs LIKE ?")
+                params.append(f'%"{entity_ref}"%')
+            conditions.append(f"({' OR '.join(entity_conditions)})")
+
+        # Lineage filtering
+        if filter.has_supersedes is not None:
+            if filter.has_supersedes:
+                conditions.append("supersedes IS NOT NULL")
+            else:
+                conditions.append("supersedes IS NULL")
+
+        if filter.has_promoted_from is not None:
+            if filter.has_promoted_from:
+                conditions.append("promoted_from IS NOT NULL")
+            else:
+                conditions.append("promoted_from IS NULL")
+
+        # Metadata filtering
+        if filter.metadata_filters:
+            for key, value in filter.metadata_filters.items():
+                # Use JSON extraction for metadata filtering
+                conditions.append(f"json_extract(metadata, '$.{key}') = ?")
+                params.append(json.dumps(value) if not isinstance(value, str) else value)
+
+        return conditions, params
+
+    async def query(self, filter: MemoryFilter) -> list[Memory]:
+        """Query memories matching the given filter.
+
+        Args:
+            filter: Filter criteria for the query.
+
+        Returns:
+            List of matching memories.
+        """
+        conditions, params = self._build_query_conditions(filter)
+
+        # Build WHERE clause
+        where_clause = " AND ".join(conditions) if conditions else "1=1"
+
+        # Build ORDER BY clause
+        order_column = filter.order_by
+        if order_column not in (
+            "created_at",
+            "importance",
+            "access_count",
+            "last_accessed",
+        ):
+            order_column = "created_at"
+
+        order_direction = "DESC" if filter.order_desc else "ASC"
+
+        # Build full query
+        query = f"""
+            SELECT * FROM memories
+            WHERE {where_clause}
+            ORDER BY {order_column} {order_direction}
+        """
+
+        # Add pagination
+        if filter.limit is not None:
+            query += f" LIMIT {filter.limit}"
+
+        if filter.offset > 0:
+            query += f" OFFSET {filter.offset}"
+
+        with self._get_conn() as conn:
+            cursor = conn.execute(query, params)
+            return [self._row_to_memory(row) for row in cursor]
+
+    async def count(self, filter: MemoryFilter) -> int:
+        """Count memories matching the given filter.
+
+        Args:
+            filter: Filter criteria for the count.
+
+        Returns:
+            Number of matching memories.
+        """
+        conditions, params = self._build_query_conditions(filter)
+
+        where_clause = " AND ".join(conditions) if conditions else "1=1"
+
+        query = f"SELECT COUNT(*) FROM memories WHERE {where_clause}"
+
+        with self._get_conn() as conn:
+            cursor = conn.execute(query, params)
+            result = cursor.fetchone()[0]
+            return int(result)
+
+    async def supersede(
+        self,
+        old_memory_id: str,
+        new_memory: Memory,
+        supersede_time: datetime | None = None,
+    ) -> Memory:
+        """Supersede an existing memory with a new version.
+
+        This creates a temporal chain: the old memory's valid_until is set,
+        and the new memory's supersedes field points to the old one.
+
+        Args:
+            old_memory_id: ID of the memory to supersede.
+            new_memory: The new memory that replaces it.
+            supersede_time: When the supersession occurred (defaults to now).
+
+        Returns:
+            The saved new memory with lineage fields populated.
+
+        Raises:
+            ValueError: If the old memory is not found.
+        """
+        if supersede_time is None:
+            supersede_time = datetime.utcnow()
+
+        # Get the old memory
+        old_memory = await self.get(old_memory_id)
+        if old_memory is None:
+            raise ValueError(f"Memory with ID {old_memory_id} not found")
+
+        # Update old memory's valid_until and superseded_by
+        old_memory.valid_until = supersede_time
+        old_memory.superseded_by = new_memory.id
+
+        # Set up new memory's lineage
+        new_memory.supersedes = old_memory_id
+        new_memory.valid_from = supersede_time
+
+        # Save both in a transaction
+        with self._get_conn() as conn:
+            # Update old memory
+            conn.execute(
+                """
+                UPDATE memories
+                SET valid_until = ?, superseded_by = ?
+                WHERE id = ?
+                """,
+                (supersede_time.isoformat(), new_memory.id, old_memory_id),
+            )
+
+            # Insert new memory
+            row = self._memory_to_row(new_memory)
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO memories (
+                    id, content, user_id, session_id, agent_id, turn_id,
+                    created_at, valid_from, valid_until,
+                    category, importance,
+                    supersedes, superseded_by, promoted_from, promotion_chain,
+                    access_count, last_accessed,
+                    entity_refs, embedding, metadata
+                ) VALUES (
+                    :id, :content, :user_id, :session_id, :agent_id, :turn_id,
+                    :created_at, :valid_from, :valid_until,
+                    :category, :importance,
+                    :supersedes, :superseded_by, :promoted_from, :promotion_chain,
+                    :access_count, :last_accessed,
+                    :entity_refs, :embedding, :metadata
+                )
+                """,
+                row,
+            )
+            conn.commit()
+
+        return new_memory
+
+    async def get_history(
+        self,
+        memory_id: str,
+        include_future: bool = False,
+    ) -> list[Memory]:
+        """Get the full history chain for a memory.
+
+        Follows the supersedes/superseded_by chain to return all versions.
+
+        Args:
+            memory_id: ID of any memory in the chain.
+            include_future: Whether to include memories that superseded this one.
+
+        Returns:
+            List of memories in temporal order (oldest first).
+        """
+        # Start with the given memory
+        current = await self.get(memory_id)
+        if current is None:
+            return []
+
+        history: list[Memory] = [current]
+
+        # Follow chain backwards (supersedes)
+        back_id = current.supersedes
+        while back_id is not None:
+            prev = await self.get(back_id)
+            if prev is None:
+                break
+            history.insert(0, prev)  # Add to beginning
+            back_id = prev.supersedes
+
+        # Follow chain forwards (superseded_by) if requested
+        if include_future:
+            forward_id = current.superseded_by
+            while forward_id is not None:
+                next_mem = await self.get(forward_id)
+                if next_mem is None:
+                    break
+                history.append(next_mem)
+                forward_id = next_mem.superseded_by
+
+        return history
+
+    async def clear_scope(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        turn_id: str | None = None,
+    ) -> int:
+        """Clear all memories at or below a scope level.
+
+        Args:
+            user_id: Required user scope.
+            session_id: If provided, clear session and below.
+            agent_id: If provided, clear agent and below.
+            turn_id: If provided, clear only that turn.
+
+        Returns:
+            Number of memories deleted.
+        """
+        conditions = ["user_id = ?"]
+        params: list[Any] = [user_id]
+
+        if turn_id is not None:
+            # Clear only specific turn
+            conditions.append("turn_id = ?")
+            params.append(turn_id)
+        elif agent_id is not None:
+            # Clear agent and its turns
+            conditions.append("agent_id = ?")
+            params.append(agent_id)
+        elif session_id is not None:
+            # Clear session and its agents/turns
+            conditions.append("session_id = ?")
+            params.append(session_id)
+        # If only user_id, clear all user's memories
+
+        where_clause = " AND ".join(conditions)
+
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM memories WHERE {where_clause}",
+                params,
+            )
+            conn.commit()
+            return cursor.rowcount
+
+    async def clear_all(self) -> int:
+        """Clear all memories from the store.
+
+        Returns:
+            Number of memories deleted.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute("DELETE FROM memories")
+            conn.commit()
+            return cursor.rowcount
+
+    def count_sync(self) -> int:
+        """Synchronous count of all memories (for diagnostics).
+
+        Returns:
+            Total number of memories in the store.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute("SELECT COUNT(*) FROM memories")
+            result = cursor.fetchone()[0]
+            return int(result)

headroom/memory/config.py

@@ -0,0 +1,144 @@
+"""Configuration dataclasses for Headroom's hierarchical memory system.
+
+Provides configuration options for all pluggable components:
+- Storage backends (SQLite, future: PostgreSQL, DynamoDB)
+- Vector index backends (HNSW, future: FAISS, Pinecone)
+- Text index backends (FTS5, future: Elasticsearch)
+- Embedder backends (local sentence-transformers, OpenAI, Ollama)
+- Caching options
+- Bubbling behavior defaults
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from headroom.memory.models import ScopeLevel
+
+
+class StoreBackend(Enum):
+    """Supported memory store backends."""
+
+    SQLITE = "sqlite"
+    # Future: POSTGRES = "postgres", DYNAMODB = "dynamodb"
+
+
+class VectorBackend(Enum):
+    """Supported vector index backends."""
+
+    HNSW = "hnsw"
+    # Future: FAISS = "faiss", PINECONE = "pinecone"
+
+
+class TextBackend(Enum):
+    """Supported text index backends."""
+
+    FTS5 = "fts5"
+    # Future: ELASTICSEARCH = "elasticsearch"
+
+
+class EmbedderBackend(Enum):
+    """Supported embedder backends."""
+
+    LOCAL = "local"  # sentence-transformers
+    OPENAI = "openai"
+    OLLAMA = "ollama"
+
+
+@dataclass
+class MemoryConfig:
+    """Complete configuration for the memory system.
+
+    This dataclass holds all configuration options needed to initialize
+    the memory system components. Each component can be configured
+    independently, allowing for flexible deployment scenarios.
+
+    Attributes:
+        store_backend: Which storage backend to use for memory persistence.
+        db_path: Path to the database file (for file-based backends like SQLite).
+
+        vector_backend: Which vector index backend to use for similarity search.
+        vector_dimension: Dimension of embedding vectors.
+        hnsw_ef_construction: HNSW index build-time accuracy parameter.
+        hnsw_m: HNSW maximum number of connections per node.
+        hnsw_ef_search: HNSW search-time accuracy parameter.
+
+        text_backend: Which text index backend to use for full-text search.
+
+        embedder_backend: Which embedder to use for generating embeddings.
+        embedder_model: Model name/identifier for the embedder.
+        openai_api_key: API key for OpenAI embeddings (if using OpenAI backend).
+        ollama_base_url: Base URL for Ollama server (if using Ollama backend).
+
+        cache_enabled: Whether to enable the memory cache layer.
+        cache_max_size: Maximum number of entries in the cache.
+
+        auto_bubble: Whether to automatically bubble memories up the hierarchy.
+        preference_bubble_to: Default scope level for bubbling preferences.
+        decision_bubble_to: Default scope level for bubbling decisions.
+
+    Example:
+        config = MemoryConfig(
+            db_path=Path("./my_memory.db"),
+            embedder_backend=EmbedderBackend.OPENAI,
+            openai_api_key="sk-...",
+            cache_max_size=2000,
+        )
+    """
+
+    # Storage
+    store_backend: StoreBackend = StoreBackend.SQLITE
+    db_path: Path = field(default_factory=lambda: Path("headroom_memory.db"))
+
+    # Vector index
+    vector_backend: VectorBackend = VectorBackend.HNSW
+    vector_dimension: int = 384
+    hnsw_ef_construction: int = 200
+    hnsw_m: int = 16
+    hnsw_ef_search: int = 50
+
+    # Text index
+    text_backend: TextBackend = TextBackend.FTS5
+
+    # Embedder
+    embedder_backend: EmbedderBackend = EmbedderBackend.LOCAL
+    embedder_model: str = "all-MiniLM-L6-v2"
+    openai_api_key: str | None = None
+    ollama_base_url: str = "http://localhost:11434"
+
+    # Cache
+    cache_enabled: bool = True
+    cache_max_size: int = 1000
+
+    # Bubbling defaults
+    auto_bubble: bool = True
+    preference_bubble_to: ScopeLevel = ScopeLevel.USER
+    decision_bubble_to: ScopeLevel = ScopeLevel.SESSION
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if self.vector_dimension < 1:
+            raise ValueError(f"vector_dimension must be positive, got {self.vector_dimension}")
+
+        if self.hnsw_ef_construction < 1:
+            raise ValueError(
+                f"hnsw_ef_construction must be positive, got {self.hnsw_ef_construction}"
+            )
+
+        if self.hnsw_m < 1:
+            raise ValueError(f"hnsw_m must be positive, got {self.hnsw_m}")
+
+        if self.hnsw_ef_search < 1:
+            raise ValueError(f"hnsw_ef_search must be positive, got {self.hnsw_ef_search}")
+
+        if self.cache_max_size < 1:
+            raise ValueError(f"cache_max_size must be positive, got {self.cache_max_size}")
+
+        if self.embedder_backend == EmbedderBackend.OPENAI and not self.openai_api_key:
+            raise ValueError("openai_api_key is required when using OpenAI embedder backend")
+
+        # Ensure db_path is a Path object
+        if isinstance(self.db_path, str):
+            self.db_path = Path(self.db_path)

headroom/memory/core.py

@@ -0,0 +1,893 @@
+"""Core HierarchicalMemory orchestrator for Headroom.
+
+This module provides the main HierarchicalMemory class that coordinates
+all memory system components: store, vector index, text index, embedder,
+and cache. It implements the high-level memory operations with automatic
+embedding, indexing, caching, and memory bubbling.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from headroom.memory.config import MemoryConfig
+from headroom.memory.factory import create_memory_system
+from headroom.memory.models import Memory, MemoryCategory, ScopeLevel
+from headroom.memory.ports import MemoryFilter, TextFilter, VectorFilter
+
+if TYPE_CHECKING:
+    from headroom.memory.ports import (
+        Embedder,
+        MemoryCache,
+        MemoryStore,
+        TextIndex,
+        TextSearchResult,
+        VectorIndex,
+        VectorSearchResult,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class HierarchicalMemory:
+    """Main orchestrator for the hierarchical memory system.
+
+    HierarchicalMemory coordinates all memory system components to provide
+    a unified API for memory operations. It handles:
+    - Automatic embedding generation
+    - Multi-index updates (store, vector, text)
+    - Cache management
+    - Memory bubbling (promoting important memories up the hierarchy)
+    - Hierarchical scoping (user -> session -> agent -> turn)
+    - Temporal queries (point-in-time, supersession)
+
+    Usage:
+        # Create with default configuration
+        memory = await HierarchicalMemory.create()
+
+        # Or with custom configuration
+        config = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI)
+        memory = await HierarchicalMemory.create(config)
+
+        # Add a memory
+        await memory.add(
+            content="User prefers Python over JavaScript",
+            user_id="alice",
+            category=MemoryCategory.PREFERENCE,
+            importance=0.9,
+        )
+
+        # Search semantically
+        results = await memory.search("programming language preferences", user_id="alice")
+
+        # Full-text search
+        results = await memory.text_search("Python", user_id="alice")
+
+        # Query with filters
+        memories = await memory.query(MemoryFilter(
+            user_id="alice",
+            categories=[MemoryCategory.PREFERENCE],
+            min_importance=0.8,
+        ))
+    """
+
+    def __init__(
+        self,
+        store: MemoryStore,
+        vector_index: VectorIndex,
+        text_index: TextIndex,
+        embedder: Embedder,
+        cache: MemoryCache | None = None,
+        config: MemoryConfig | None = None,
+    ) -> None:
+        """Initialize HierarchicalMemory with components.
+
+        Prefer using the create() factory method instead of direct initialization.
+
+        Args:
+            store: Memory persistence backend.
+            vector_index: Vector similarity search index.
+            text_index: Full-text search index.
+            embedder: Text embedding generator.
+            cache: Optional memory cache.
+            config: Configuration (for bubbling settings, etc.).
+        """
+        self._store = store
+        self._vector_index = vector_index
+        self._text_index = text_index
+        self._embedder = embedder
+        self._cache = cache
+        self._config = config or MemoryConfig()
+
+    @classmethod
+    async def create(cls, config: MemoryConfig | None = None) -> HierarchicalMemory:
+        """Create a HierarchicalMemory instance from configuration.
+
+        This is the recommended way to create a HierarchicalMemory instance.
+        It creates all necessary components based on the configuration.
+
+        Args:
+            config: Memory system configuration. Uses defaults if not provided.
+
+        Returns:
+            Fully initialized HierarchicalMemory instance.
+
+        Example:
+            memory = await HierarchicalMemory.create()
+            # Or with config
+            memory = await HierarchicalMemory.create(MemoryConfig(
+                embedder_backend=EmbedderBackend.OPENAI,
+                openai_api_key="sk-...",
+            ))
+        """
+        config = config or MemoryConfig()
+        store, vector_index, text_index, embedder, cache = await create_memory_system(config)
+        return cls(store, vector_index, text_index, embedder, cache, config)
+
+    # =========================================================================
+    # Memory Creation
+    # =========================================================================
+
+    async def add(
+        self,
+        content: str,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        turn_id: str | None = None,
+        category: MemoryCategory = MemoryCategory.FACT,
+        importance: float = 0.5,
+        entity_refs: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        auto_embed: bool = True,
+        auto_bubble: bool | None = None,
+    ) -> Memory:
+        """Add a new memory to the system.
+
+        Creates a memory with the specified content and scope, generates
+        embeddings, and indexes it for search. Optionally bubbles important
+        memories up the hierarchy.
+
+        Args:
+            content: The memory content/text.
+            user_id: User identifier (required - top of hierarchy).
+            session_id: Session identifier (optional).
+            agent_id: Agent identifier (optional).
+            turn_id: Turn identifier (optional).
+            category: Memory classification.
+            importance: Importance score (0.0 - 1.0).
+            entity_refs: List of entity references.
+            metadata: Additional metadata.
+            auto_embed: Whether to generate embedding automatically.
+            auto_bubble: Whether to bubble up (uses config default if None).
+
+        Returns:
+            The created and stored Memory object.
+
+        Example:
+            memory = await system.add(
+                content="User prefers dark mode",
+                user_id="alice",
+                session_id="sess-123",
+                category=MemoryCategory.PREFERENCE,
+                importance=0.8,
+            )
+        """
+        # Create memory object
+        memory = Memory(
+            content=content,
+            user_id=user_id,
+            session_id=session_id,
+            agent_id=agent_id,
+            turn_id=turn_id,
+            category=category,
+            importance=importance,
+            entity_refs=entity_refs or [],
+            metadata=metadata or {},
+        )
+
+        # Generate embedding if requested
+        if auto_embed:
+            embedding = await self._embedder.embed(content)
+            memory.embedding = embedding
+
+        # Save to store
+        await self._store.save(memory)
+
+        # Index for vector search
+        if memory.embedding is not None:
+            await self._vector_index.index(memory)
+
+        # Index for text search
+        await self._index_for_text_search(memory)
+
+        # Update cache
+        if self._cache is not None:
+            await self._cache.put(memory)
+
+        # Handle bubbling
+        should_bubble = auto_bubble if auto_bubble is not None else self._config.auto_bubble
+        if should_bubble:
+            await self._maybe_bubble(memory)
+
+        logger.debug(f"Added memory {memory.id} at scope {memory.scope_level.value}")
+        return memory
+
+    async def add_batch(
+        self,
+        memories_data: list[dict[str, Any]],
+        auto_embed: bool = True,
+    ) -> list[Memory]:
+        """Add multiple memories in a batch operation.
+
+        More efficient than calling add() multiple times due to batch
+        embedding and batch database operations.
+
+        Args:
+            memories_data: List of dicts with memory parameters
+                          (content, user_id, etc.).
+            auto_embed: Whether to generate embeddings automatically.
+
+        Returns:
+            List of created Memory objects.
+
+        Example:
+            memories = await system.add_batch([
+                {"content": "Fact 1", "user_id": "alice"},
+                {"content": "Fact 2", "user_id": "alice"},
+            ])
+        """
+        # Create Memory objects
+        memories: list[Memory] = []
+        for data in memories_data:
+            memory = Memory(
+                content=data["content"],
+                user_id=data["user_id"],
+                session_id=data.get("session_id"),
+                agent_id=data.get("agent_id"),
+                turn_id=data.get("turn_id"),
+                category=data.get("category", MemoryCategory.FACT),
+                importance=data.get("importance", 0.5),
+                entity_refs=data.get("entity_refs", []),
+                metadata=data.get("metadata", {}),
+            )
+            memories.append(memory)
+
+        # Batch embed
+        if auto_embed:
+            texts = [m.content for m in memories]
+            embeddings = await self._embedder.embed_batch(texts)
+            for memory, embedding in zip(memories, embeddings):
+                memory.embedding = embedding
+
+        # Batch save
+        await self._store.save_batch(memories)
+
+        # Batch index for vector search
+        memories_with_embeddings = [m for m in memories if m.embedding is not None]
+        if memories_with_embeddings:
+            await self._vector_index.index_batch(memories_with_embeddings)
+
+        # Index for text search
+        for memory in memories:
+            await self._index_for_text_search(memory)
+
+        # Update cache
+        if self._cache is not None:
+            await self._cache.put_batch(memories)
+
+        logger.debug(f"Added batch of {len(memories)} memories")
+        return memories
+
+    # =========================================================================
+    # Memory Retrieval
+    # =========================================================================
+
+    async def get(self, memory_id: str) -> Memory | None:
+        """Get a memory by ID.
+
+        Checks cache first, then falls back to store.
+
+        Args:
+            memory_id: The unique memory identifier.
+
+        Returns:
+            The Memory if found, None otherwise.
+        """
+        # Check cache first
+        if self._cache is not None:
+            cached = await self._cache.get(memory_id)
+            if cached is not None:
+                return cached
+
+        # Fall back to store
+        memory = await self._store.get(memory_id)
+
+        # Update cache on hit
+        if memory is not None and self._cache is not None:
+            await self._cache.put(memory)
+
+        return memory
+
+    async def query(self, filter: MemoryFilter) -> list[Memory]:
+        """Query memories with filtering.
+
+        Args:
+            filter: Filter criteria for the query.
+
+        Returns:
+            List of matching memories.
+
+        Example:
+            memories = await system.query(MemoryFilter(
+                user_id="alice",
+                categories=[MemoryCategory.PREFERENCE],
+                min_importance=0.7,
+                limit=10,
+            ))
+        """
+        return await self._store.query(filter)
+
+    async def count(self, filter: MemoryFilter) -> int:
+        """Count memories matching filter criteria.
+
+        Args:
+            filter: Filter criteria.
+
+        Returns:
+            Number of matching memories.
+        """
+        return await self._store.count(filter)
+
+    # =========================================================================
+    # Search Operations
+    # =========================================================================
+
+    async def search(
+        self,
+        query: str,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        top_k: int = 10,
+        min_similarity: float = 0.0,
+        categories: list[MemoryCategory] | None = None,
+        scope_levels: list[ScopeLevel] | None = None,
+        include_superseded: bool = False,
+    ) -> list[VectorSearchResult]:
+        """Semantic search for similar memories.
+
+        Uses vector similarity to find memories semantically similar
+        to the query text.
+
+        Args:
+            query: Search query text.
+            user_id: Filter by user.
+            session_id: Filter by session.
+            agent_id: Filter by agent.
+            top_k: Maximum number of results.
+            min_similarity: Minimum cosine similarity threshold.
+            categories: Filter by categories.
+            scope_levels: Filter by scope levels.
+            include_superseded: Include superseded memories.
+
+        Returns:
+            List of VectorSearchResult sorted by similarity.
+
+        Example:
+            results = await system.search(
+                "programming preferences",
+                user_id="alice",
+                top_k=5,
+            )
+            for result in results:
+                print(f"{result.similarity:.2f}: {result.memory.content}")
+        """
+        # Embed query
+        query_vector = await self._embedder.embed(query)
+
+        # Build filter
+        vector_filter = VectorFilter(
+            query_vector=query_vector,
+            top_k=top_k,
+            min_similarity=min_similarity,
+            user_id=user_id,
+            session_id=session_id,
+            agent_id=agent_id,
+            categories=categories,
+            scope_levels=scope_levels,
+            include_superseded=include_superseded,
+        )
+
+        return await self._vector_index.search(vector_filter)
+
+    async def text_search(
+        self,
+        query: str,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        limit: int = 100,
+        categories: list[MemoryCategory] | None = None,
+    ) -> list[TextSearchResult]:
+        """Full-text search for memories.
+
+        Uses keyword matching with BM25 ranking to find memories
+        containing the search terms.
+
+        Args:
+            query: Search query text.
+            user_id: Filter by user.
+            session_id: Filter by session.
+            limit: Maximum number of results.
+            categories: Filter by categories.
+
+        Returns:
+            List of TextSearchResult sorted by relevance.
+
+        Example:
+            results = await system.text_search("Python", user_id="alice")
+        """
+        text_filter = TextFilter(
+            query=query,
+            user_id=user_id,
+            session_id=session_id,
+            limit=limit,
+            categories=categories,
+        )
+
+        return await self._text_index.search(text_filter)
+
+    # =========================================================================
+    # Memory Updates
+    # =========================================================================
+
+    async def update(
+        self,
+        memory_id: str,
+        content: str | None = None,
+        importance: float | None = None,
+        category: MemoryCategory | None = None,
+        entity_refs: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        re_embed: bool = True,
+    ) -> Memory | None:
+        """Update an existing memory.
+
+        Updates the specified fields and re-indexes if content changes.
+
+        Args:
+            memory_id: ID of memory to update.
+            content: New content (triggers re-embedding if re_embed=True).
+            importance: New importance score.
+            category: New category.
+            entity_refs: New entity references.
+            metadata: New or updated metadata (merged with existing).
+            re_embed: Whether to regenerate embedding on content change.
+
+        Returns:
+            Updated Memory, or None if not found.
+        """
+        memory = await self._store.get(memory_id)
+        if memory is None:
+            return None
+
+        content_changed = False
+
+        if content is not None and content != memory.content:
+            memory.content = content
+            content_changed = True
+
+        if importance is not None:
+            memory.importance = importance
+
+        if category is not None:
+            memory.category = category
+
+        if entity_refs is not None:
+            memory.entity_refs = entity_refs
+
+        if metadata is not None:
+            memory.metadata.update(metadata)
+
+        # Re-embed if content changed
+        if content_changed and re_embed:
+            memory.embedding = await self._embedder.embed(memory.content)
+
+        # Save updates
+        await self._store.save(memory)
+
+        # Update indexes
+        if content_changed:
+            if memory.embedding is not None:
+                await self._vector_index.index(memory)
+            await self._index_for_text_search(memory)
+
+        # Invalidate and re-cache
+        if self._cache is not None:
+            await self._cache.invalidate(memory_id)
+            await self._cache.put(memory)
+
+        return memory
+
+    async def supersede(
+        self,
+        old_memory_id: str,
+        new_content: str,
+        supersede_time: datetime | None = None,
+        auto_embed: bool = True,
+    ) -> Memory:
+        """Supersede an existing memory with a new version.
+
+        Creates a temporal chain where the old memory's validity ends
+        and the new memory begins. Both are kept for historical queries.
+
+        Args:
+            old_memory_id: ID of memory to supersede.
+            new_content: Content for the new memory.
+            supersede_time: When the supersession occurred (default: now).
+            auto_embed: Whether to embed the new content.
+
+        Returns:
+            The new Memory that supersedes the old one.
+
+        Raises:
+            ValueError: If old memory not found.
+
+        Example:
+            # User's preference changed
+            new_mem = await system.supersede(
+                old_memory.id,
+                "User now prefers JavaScript over Python",
+            )
+        """
+        # Get old memory
+        old_memory = await self._store.get(old_memory_id)
+        if old_memory is None:
+            raise ValueError(f"Memory {old_memory_id} not found")
+
+        # Create new memory with same scope
+        new_memory = Memory(
+            content=new_content,
+            user_id=old_memory.user_id,
+            session_id=old_memory.session_id,
+            agent_id=old_memory.agent_id,
+            turn_id=old_memory.turn_id,
+            category=old_memory.category,
+            importance=old_memory.importance,
+            entity_refs=old_memory.entity_refs.copy(),
+            metadata=old_memory.metadata.copy(),
+        )
+
+        # Embed new content
+        if auto_embed:
+            new_memory.embedding = await self._embedder.embed(new_content)
+
+        # Perform supersession in store
+        new_memory = await self._store.supersede(old_memory_id, new_memory, supersede_time)
+
+        # Update indexes
+        if new_memory.embedding is not None:
+            await self._vector_index.index(new_memory)
+        await self._index_for_text_search(new_memory)
+
+        # Update cache
+        if self._cache is not None:
+            await self._cache.invalidate(old_memory_id)
+            await self._cache.put(new_memory)
+
+        logger.debug(f"Superseded memory {old_memory_id} with {new_memory.id}")
+        return new_memory
+
+    async def get_history(
+        self,
+        memory_id: str,
+        include_future: bool = False,
+    ) -> list[Memory]:
+        """Get the full history chain for a memory.
+
+        Follows supersession links to return all versions of a memory.
+
+        Args:
+            memory_id: ID of any memory in the chain.
+            include_future: Whether to include memories that superseded this one.
+
+        Returns:
+            List of memories in temporal order (oldest first).
+        """
+        return await self._store.get_history(memory_id, include_future)
+
+    # =========================================================================
+    # Memory Deletion
+    # =========================================================================
+
+    async def delete(self, memory_id: str) -> bool:
+        """Delete a memory from all indexes.
+
+        Args:
+            memory_id: ID of memory to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        # Delete from store
+        deleted = await self._store.delete(memory_id)
+
+        if deleted:
+            # Remove from indexes
+            await self._vector_index.remove(memory_id)
+            await self._text_index.remove(memory_id)
+
+            # Invalidate cache
+            if self._cache is not None:
+                await self._cache.invalidate(memory_id)
+
+        return deleted
+
+    async def clear_scope(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        turn_id: str | None = None,
+    ) -> int:
+        """Clear all memories at or below a scope level.
+
+        Args:
+            user_id: Required user scope.
+            session_id: If provided, clear session and below.
+            agent_id: If provided, clear agent and below.
+            turn_id: If provided, clear only that turn.
+
+        Returns:
+            Number of memories deleted.
+        """
+        # Get IDs of memories to clear
+        filter = MemoryFilter(
+            user_id=user_id,
+            session_id=session_id,
+            agent_id=agent_id,
+            turn_id=turn_id,
+            include_superseded=True,  # Clear all versions
+        )
+        memories = await self._store.query(filter)
+        memory_ids = [m.id for m in memories]
+
+        if not memory_ids:
+            return 0
+
+        # Clear from store
+        count = await self._store.clear_scope(user_id, session_id, agent_id, turn_id)
+
+        # Clear from indexes
+        await self._vector_index.remove_batch(memory_ids)
+        for mid in memory_ids:
+            await self._text_index.remove(mid)
+
+        # Clear from cache
+        if self._cache is not None:
+            await self._cache.invalidate_scope(user_id, session_id, agent_id)
+
+        logger.debug(f"Cleared {count} memories at scope user={user_id}, session={session_id}")
+        return count
+
+    # =========================================================================
+    # Convenience Methods
+    # =========================================================================
+
+    async def remember(
+        self,
+        content: str,
+        user_id: str,
+        session_id: str | None = None,
+        category: MemoryCategory = MemoryCategory.FACT,
+        importance: float = 0.5,
+    ) -> Memory:
+        """Convenience method to quickly add a memory.
+
+        Shorthand for add() with common parameters.
+
+        Args:
+            content: What to remember.
+            user_id: Who it's for.
+            session_id: Optional session context.
+            category: Memory category.
+            importance: How important (0.0 - 1.0).
+
+        Returns:
+            The created Memory.
+
+        Example:
+            await system.remember("Likes coffee", user_id="alice", importance=0.7)
+        """
+        return await self.add(
+            content=content,
+            user_id=user_id,
+            session_id=session_id,
+            category=category,
+            importance=importance,
+        )
+
+    async def recall(
+        self,
+        query: str,
+        user_id: str,
+        top_k: int = 5,
+    ) -> list[Memory]:
+        """Convenience method to recall relevant memories.
+
+        Performs semantic search and returns just the Memory objects.
+
+        Args:
+            query: What to recall.
+            user_id: Whose memories to search.
+            top_k: Maximum memories to return.
+
+        Returns:
+            List of relevant Memory objects.
+
+        Example:
+            memories = await system.recall("coffee preferences", user_id="alice")
+        """
+        results = await self.search(query, user_id=user_id, top_k=top_k)
+        return [r.memory for r in results]
+
+    async def get_user_memories(
+        self,
+        user_id: str,
+        limit: int = 100,
+        include_sessions: bool = True,
+    ) -> list[Memory]:
+        """Get all memories for a user.
+
+        Args:
+            user_id: User identifier.
+            limit: Maximum memories to return.
+            include_sessions: If True, include session-level memories.
+                            If False, only return user-level memories.
+
+        Returns:
+            List of memories for the user.
+        """
+        filter = MemoryFilter(
+            user_id=user_id,
+            limit=limit,
+        )
+
+        if not include_sessions:
+            filter.scope_levels = [ScopeLevel.USER]
+
+        return await self._store.query(filter)
+
+    async def get_session_memories(
+        self,
+        user_id: str,
+        session_id: str,
+        limit: int = 100,
+    ) -> list[Memory]:
+        """Get all memories for a session.
+
+        Args:
+            user_id: User identifier.
+            session_id: Session identifier.
+            limit: Maximum memories to return.
+
+        Returns:
+            List of memories for the session.
+        """
+        filter = MemoryFilter(
+            user_id=user_id,
+            session_id=session_id,
+            limit=limit,
+        )
+        return await self._store.query(filter)
+
+    # =========================================================================
+    # Internal Methods
+    # =========================================================================
+
+    async def _index_for_text_search(self, memory: Memory) -> None:
+        """Index a memory for full-text search.
+
+        Uses the protocol-compliant async method on the text index.
+        """
+        # Use the async index_memory method which is protocol-compliant
+        await self._text_index.index_memory(memory)  # type: ignore[attr-defined]
+
+    async def _maybe_bubble(self, memory: Memory) -> None:
+        """Maybe bubble a memory up the hierarchy based on category and importance.
+
+        Bubbling creates a copy of the memory at a higher scope level.
+        Only happens if the memory meets bubbling criteria.
+        """
+        # Determine target scope based on category
+        target_scope: ScopeLevel | None = None
+
+        if memory.category == MemoryCategory.PREFERENCE:
+            target_scope = self._config.preference_bubble_to
+        elif memory.category == MemoryCategory.DECISION:
+            target_scope = self._config.decision_bubble_to
+
+        if target_scope is None:
+            return
+
+        # Check if already at or above target scope
+        current_scope = memory.scope_level
+        if self._scope_level_value(current_scope) <= self._scope_level_value(target_scope):
+            return
+
+        # Only bubble if importance is high enough (> 0.7)
+        if memory.importance < 0.7:
+            return
+
+        # Create bubbled memory at target scope
+        bubbled = Memory(
+            content=memory.content,
+            user_id=memory.user_id,
+            session_id=memory.session_id if target_scope != ScopeLevel.USER else None,
+            agent_id=None,  # Don't bubble to agent level
+            turn_id=None,
+            category=memory.category,
+            importance=memory.importance,
+            entity_refs=memory.entity_refs.copy(),
+            metadata=memory.metadata.copy(),
+            embedding=memory.embedding.copy() if memory.embedding is not None else None,
+            promoted_from=memory.id,
+            promotion_chain=memory.promotion_chain + [memory.id],
+        )
+
+        # Save bubbled memory
+        await self._store.save(bubbled)
+
+        # Index bubbled memory
+        if bubbled.embedding is not None:
+            await self._vector_index.index(bubbled)
+        await self._index_for_text_search(bubbled)
+
+        logger.debug(
+            f"Bubbled memory {memory.id} from {current_scope.value} to {target_scope.value}"
+        )
+
+    def _scope_level_value(self, level: ScopeLevel) -> int:
+        """Get numeric value for scope level (lower = broader scope)."""
+        return {
+            ScopeLevel.USER: 0,
+            ScopeLevel.SESSION: 1,
+            ScopeLevel.AGENT: 2,
+            ScopeLevel.TURN: 3,
+        }[level]
+
+    # =========================================================================
+    # Properties
+    # =========================================================================
+
+    @property
+    def store(self) -> MemoryStore:
+        """Access the underlying memory store."""
+        return self._store
+
+    @property
+    def vector_index(self) -> VectorIndex:
+        """Access the underlying vector index."""
+        return self._vector_index
+
+    @property
+    def text_index(self) -> TextIndex:
+        """Access the underlying text index."""
+        return self._text_index
+
+    @property
+    def embedder(self) -> Embedder:
+        """Access the underlying embedder."""
+        return self._embedder
+
+    @property
+    def cache(self) -> MemoryCache | None:
+        """Access the underlying cache (may be None)."""
+        return self._cache
+
+    @property
+    def config(self) -> MemoryConfig:
+        """Access the configuration."""
+        return self._config

headroom/memory/extractor.py

@@ -1,390 +0,0 @@
-"""Memory extraction using LLMs.
-
-Supports multiple providers by reusing the wrapped client with a cheap model.
-Auto-detects provider from client class and selects appropriate cheap model.
-Uses structured JSON output where available for reliable parsing.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-from typing import Any, Protocol
-
-from headroom.memory.store import Memory
-
-logger = logging.getLogger(__name__)
-
-
-# Provider → Cheap Model mapping (verified January 2026)
-# These are the most cost-effective models for simple extraction tasks
-CHEAP_MODELS: dict[str, str] = {
-    "openai": "gpt-4o-mini",  # $0.15/1M input, $0.60/1M output
-    "anthropic": "claude-3-5-haiku-latest",  # $0.80/1M input, $4/1M output
-    "mistralai": "mistral-small-latest",  # $0.10/1M input, $0.30/1M output
-    "groq": "llama-3.3-70b-versatile",  # Free tier available
-    "together": "meta-llama/Llama-3.3-70B-Instruct-Turbo",  # $0.88/1M
-    "fireworks": "accounts/fireworks/models/llama-v3p1-8b-instruct",  # $0.20/1M
-    "google": "gemini-2.0-flash-lite",  # $0.075/1M input, $0.30/1M output
-    "cohere": "command-r7b-12-2024",  # $0.0375/1M input, $0.15/1M output
-}
-
-# Providers that support structured JSON output via response_format
-SUPPORTS_JSON_MODE: set[str] = {"openai", "mistralai", "groq", "together", "fireworks"}
-
-
-# Entity-agnostic prompt - works for users, agents, or any conversational entity
-EXTRACTION_PROMPT = """Analyze this conversation and extract any facts worth remembering.
-
-Focus on:
-- Preferences (language, tools, frameworks, style, configuration)
-- Facts (identity, role, capabilities, constraints, environment)
-- Context (goals, ongoing tasks, relationships, history)
-
-Conversation:
-Speaker A: {query}
-Speaker B: {response}
-
-Return a JSON object with this structure:
-{{
-  "memories": [
-    {{"content": "Prefers Python for backend development", "category": "preference", "importance": 0.8}},
-    {{"content": "Works on distributed systems", "category": "fact", "importance": 0.7}}
-  ],
-  "should_remember": true
-}}
-
-Categories: "preference", "fact", "context"
-Importance: 0.0-1.0 (higher = more important to remember long-term)
-
-If there's nothing worth remembering (greetings, generic questions, transient info), return:
-{{"memories": [], "should_remember": false}}
-
-Return ONLY valid JSON."""
-
-
-class ChatClient(Protocol):
-    """Protocol for chat clients (OpenAI, Anthropic, etc.)."""
-
-    class Chat:
-        class Completions:
-            def create(self, **kwargs: Any) -> Any: ...
-
-        completions: Completions
-
-    chat: Chat
-
-
-def detect_provider(client: Any) -> str | None:
-    """Detect the provider from client class path.
-
-    Args:
-        client: The LLM client instance
-
-    Returns:
-        Provider name or None if unknown
-    """
-    module = type(client).__module__.lower()
-
-    # Check for known providers
-    providers = [
-        "openai",
-        "anthropic",
-        "mistralai",
-        "groq",
-        "together",
-        "fireworks",
-        "google",
-        "cohere",
-    ]
-
-    for provider in providers:
-        if provider in module:
-            return provider
-
-    return None
-
-
-def get_cheap_model(provider: str) -> str | None:
-    """Get the cheap model for a provider.
-
-    Args:
-        provider: Provider name
-
-    Returns:
-        Cheap model ID or None if unknown
-    """
-    return CHEAP_MODELS.get(provider)
-
-
-class MemoryExtractor:
-    """Extracts memories from conversations using LLMs.
-
-    Supports multiple providers by reusing the wrapped client.
-    Auto-detects provider and selects appropriate cheap model.
-
-    Usage:
-        extractor = MemoryExtractor(openai_client)
-        memories = extractor.extract("I prefer Python", "Great choice!")
-    """
-
-    def __init__(
-        self,
-        client: Any,
-        model: str | None = None,
-    ):
-        """Initialize the extractor.
-
-        Args:
-            client: LLM client (OpenAI, Anthropic, etc.)
-            model: Override the extraction model (auto-detects if None)
-        """
-        self.client = client
-        self._provider = detect_provider(client)
-        self._model: str | None = None
-
-        if model:
-            self._model = model
-        elif self._provider:
-            self._model = get_cheap_model(self._provider)
-
-        if not self._model:
-            logger.warning(
-                f"Could not detect cheap model for provider. "
-                f"Client type: {type(client).__module__}.{type(client).__name__}. "
-                f"Memory extraction may fail."
-            )
-
-    @property
-    def provider(self) -> str | None:
-        """Get the detected provider."""
-        return self._provider
-
-    @property
-    def model(self) -> str | None:
-        """Get the extraction model."""
-        return self._model
-
-    def extract(self, query: str, response: str) -> list[Memory]:
-        """Extract memories from a conversation turn.
-
-        Args:
-            query: User's message
-            response: Assistant's response
-
-        Returns:
-            List of extracted memories (may be empty)
-        """
-        if not self._model:
-            logger.warning("No extraction model configured, skipping extraction")
-            return []
-
-        prompt = EXTRACTION_PROMPT.format(query=query, response=response)
-
-        try:
-            result = self._call_llm(prompt)
-            return self._parse_response(result)
-        except Exception as e:
-            logger.error(f"Extraction failed: {e}")
-            return []
-
-    def extract_batch(self, conversations: list[tuple[str, str, str]]) -> dict[str, list[Memory]]:
-        """Extract memories from multiple conversations.
-
-        Args:
-            conversations: List of (user_id, query, response) tuples
-
-        Returns:
-            Dict mapping user_id to list of memories
-        """
-        if not conversations:
-            return {}
-
-        # Build batch prompt
-        batch_prompt = self._build_batch_prompt(conversations)
-
-        try:
-            result = self._call_llm(batch_prompt)
-            return self._parse_batch_response(result, conversations)
-        except Exception as e:
-            logger.error(f"Batch extraction failed: {e}")
-            return {}
-
-    def _call_llm(self, prompt: str) -> str:
-        """Call the LLM with the given prompt.
-
-        Uses structured JSON output (response_format) where available
-        to ensure reliable JSON parsing.
-
-        Args:
-            prompt: The prompt to send
-
-        Returns:
-            The LLM's response text
-        """
-        if self._provider == "anthropic":
-            # Anthropic uses different API - no native JSON mode yet
-            response = self.client.messages.create(
-                model=self._model,
-                max_tokens=1024,
-                messages=[{"role": "user", "content": prompt}],
-            )
-            return str(response.content[0].text)
-        elif self._provider == "cohere":
-            # Cohere uses different API
-            response = self.client.chat(
-                model=self._model,
-                message=prompt,
-            )
-            return str(response.text)
-        elif self._provider == "google":
-            # Google Gemini - use JSON response mime type
-            model = self.client.GenerativeModel(
-                self._model,
-                generation_config={"response_mime_type": "application/json"},
-            )
-            response = model.generate_content(prompt)
-            return str(response.text)
-        else:
-            # OpenAI-compatible API (OpenAI, Groq, Together, Fireworks, Mistral)
-            # Use JSON mode for structured output
-            kwargs: dict[str, Any] = {
-                "model": self._model,
-                "messages": [{"role": "user", "content": prompt}],
-                "temperature": 0.0,  # Deterministic for extraction
-            }
-
-            # Add response_format for providers that support it
-            if self._provider in SUPPORTS_JSON_MODE:
-                kwargs["response_format"] = {"type": "json_object"}
-
-            response = self.client.chat.completions.create(**kwargs)
-            return str(response.choices[0].message.content)
-
-    def _parse_response(self, text: str) -> list[Memory]:
-        """Parse LLM response into memories.
-
-        Args:
-            text: Raw LLM response
-
-        Returns:
-            List of Memory objects
-        """
-        try:
-            # Extract JSON from response (handle markdown code blocks)
-            json_match = re.search(r"```(?:json)?\s*(.*?)\s*```", text, re.DOTALL)
-            if json_match:
-                text = json_match.group(1)
-
-            data = json.loads(text.strip())
-
-            if not data.get("should_remember", False):
-                return []
-
-            memories = []
-            for item in data.get("memories", []):
-                memories.append(
-                    Memory(
-                        content=item["content"],
-                        category=item.get("category", "fact"),
-                        importance=item.get("importance", 0.5),
-                    )
-                )
-
-            return memories
-
-        except (json.JSONDecodeError, KeyError) as e:
-            logger.warning(f"Failed to parse extraction response: {e}")
-            return []
-
-    def _build_batch_prompt(self, conversations: list[tuple[str, str, str]]) -> str:
-        """Build a batch extraction prompt.
-
-        Args:
-            conversations: List of (entity_id, query, response) tuples
-
-        Returns:
-            Batch prompt string
-        """
-        lines = [
-            "Analyze these conversations and extract facts worth remembering about each entity.",
-            "",
-            "Focus on: preferences, facts, context that helps future interactions.",
-            "",
-        ]
-
-        for i, (entity_id, query, response) in enumerate(conversations):
-            lines.extend(
-                [
-                    f"--- Conversation {i + 1} (Entity: {entity_id}) ---",
-                    f"Speaker A: {query}",
-                    f"Speaker B: {response}",
-                    "",
-                ]
-            )
-
-        lines.extend(
-            [
-                "Return a JSON object mapping entity_id to their memories:",
-                "{",
-                '  "entity_123": {',
-                '    "memories": [{"content": "...", "category": "preference", "importance": 0.8}],',
-                '    "should_remember": true',
-                "  }",
-                "}",
-                "",
-                "Categories: preference, fact, context",
-                "Importance: 0.0-1.0",
-                "",
-                "Return ONLY valid JSON.",
-            ]
-        )
-
-        return "\n".join(lines)
-
-    def _parse_batch_response(
-        self,
-        text: str,
-        conversations: list[tuple[str, str, str]],
-    ) -> dict[str, list[Memory]]:
-        """Parse batch extraction response.
-
-        Args:
-            text: Raw LLM response
-            conversations: Original conversations for fallback
-
-        Returns:
-            Dict mapping user_id to list of memories
-        """
-        try:
-            # Extract JSON from response
-            json_match = re.search(r"```(?:json)?\s*(.*?)\s*```", text, re.DOTALL)
-            if json_match:
-                text = json_match.group(1)
-
-            data = json.loads(text.strip())
-            result: dict[str, list[Memory]] = {}
-
-            for user_id, user_data in data.items():
-                if not user_data.get("should_remember", False):
-                    continue
-
-                memories = []
-                for item in user_data.get("memories", []):
-                    memories.append(
-                        Memory(
-                            content=item["content"],
-                            category=item.get("category", "fact"),
-                            importance=item.get("importance", 0.5),
-                        )
-                    )
-
-                if memories:
-                    result[user_id] = memories
-
-            return result
-
-        except (json.JSONDecodeError, KeyError, AttributeError) as e:
-            logger.warning(f"Failed to parse batch response: {e}")
-            return {}

headroom/memory/factory.py

@@ -0,0 +1,190 @@
+"""Factory module for creating memory system components.
+
+Provides a unified factory function that creates all memory system components
+from a single configuration object, ensuring consistent initialization
+and proper wiring between components.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from headroom.memory.config import (
+    EmbedderBackend,
+    MemoryConfig,
+    StoreBackend,
+    TextBackend,
+    VectorBackend,
+)
+
+if TYPE_CHECKING:
+    from headroom.memory.ports import Embedder, MemoryCache, MemoryStore, TextIndex, VectorIndex
+
+
+async def create_memory_system(
+    config: MemoryConfig | None = None,
+) -> tuple[MemoryStore, VectorIndex, TextIndex, Embedder, MemoryCache | None]:
+    """Create a complete memory system from configuration.
+
+    This factory function creates and initializes all memory system components
+    based on the provided configuration. Components are created in dependency
+    order to ensure proper initialization.
+
+    Args:
+        config: Memory system configuration. If None, uses default configuration.
+
+    Returns:
+        A tuple of (store, vector_index, text_index, embedder, cache) where:
+        - store: The memory persistence backend
+        - vector_index: The vector similarity search index
+        - text_index: The full-text search index
+        - embedder: The text embedding generator
+        - cache: The memory cache (or None if caching is disabled)
+
+    Raises:
+        ValueError: If an unknown backend type is specified in the config.
+
+    Example:
+        config = MemoryConfig(
+            embedder_backend=EmbedderBackend.LOCAL,
+            cache_max_size=2000,
+        )
+        store, vector, text, embedder, cache = await create_memory_system(config)
+    """
+    config = config or MemoryConfig()
+
+    # Create store
+    store = _create_store(config)
+
+    # Create embedder (needed by vector index for text queries)
+    embedder = _create_embedder(config)
+
+    # Create vector index
+    vector_index = _create_vector_index(config)
+
+    # Create text index
+    text_index = _create_text_index(config)
+
+    # Create cache (optional)
+    cache = _create_cache(config) if config.cache_enabled else None
+
+    return store, vector_index, text_index, embedder, cache
+
+
+def _create_store(config: MemoryConfig) -> MemoryStore:
+    """Create a memory store backend.
+
+    Args:
+        config: Memory system configuration.
+
+    Returns:
+        A MemoryStore implementation based on config.store_backend.
+
+    Raises:
+        ValueError: If the store backend is not supported.
+    """
+    if config.store_backend == StoreBackend.SQLITE:
+        from headroom.memory.adapters.sqlite import SQLiteMemoryStore
+
+        return SQLiteMemoryStore(config.db_path)
+
+    raise ValueError(f"Unknown store backend: {config.store_backend}")
+
+
+def _create_embedder(config: MemoryConfig) -> Embedder:
+    """Create an embedder backend.
+
+    Args:
+        config: Memory system configuration.
+
+    Returns:
+        An Embedder implementation based on config.embedder_backend.
+
+    Raises:
+        ValueError: If the embedder backend is not supported.
+    """
+    if config.embedder_backend == EmbedderBackend.LOCAL:
+        from headroom.memory.adapters.embedders import LocalEmbedder
+
+        return LocalEmbedder(model_name=config.embedder_model)
+
+    if config.embedder_backend == EmbedderBackend.OPENAI:
+        from headroom.memory.adapters.embedders import OpenAIEmbedder
+
+        if not config.openai_api_key:
+            raise ValueError("openai_api_key is required for OpenAI embedder")
+        return OpenAIEmbedder(
+            api_key=config.openai_api_key,
+            model_name=config.embedder_model,
+        )
+
+    if config.embedder_backend == EmbedderBackend.OLLAMA:
+        from headroom.memory.adapters.embedders import OllamaEmbedder
+
+        return OllamaEmbedder(
+            base_url=config.ollama_base_url,
+            model_name=config.embedder_model,
+        )
+
+    raise ValueError(f"Unknown embedder backend: {config.embedder_backend}")
+
+
+def _create_vector_index(config: MemoryConfig) -> VectorIndex:
+    """Create a vector index backend.
+
+    Args:
+        config: Memory system configuration.
+
+    Returns:
+        A VectorIndex implementation based on config.vector_backend.
+
+    Raises:
+        ValueError: If the vector backend is not supported.
+    """
+    if config.vector_backend == VectorBackend.HNSW:
+        from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+        return HNSWVectorIndex(
+            dimension=config.vector_dimension,
+            ef_construction=config.hnsw_ef_construction,
+            m=config.hnsw_m,
+            ef_search=config.hnsw_ef_search,
+        )
+
+    raise ValueError(f"Unknown vector backend: {config.vector_backend}")
+
+
+def _create_text_index(config: MemoryConfig) -> TextIndex:
+    """Create a text index backend.
+
+    Args:
+        config: Memory system configuration.
+
+    Returns:
+        A TextIndex implementation based on config.text_backend.
+
+    Raises:
+        ValueError: If the text backend is not supported.
+    """
+    if config.text_backend == TextBackend.FTS5:
+        from headroom.memory.adapters.fts5 import FTS5TextIndex
+
+        # FTS5TextIndex has a compatible interface but different method signatures
+        return FTS5TextIndex(db_path=config.db_path)  # type: ignore[return-value]
+
+    raise ValueError(f"Unknown text backend: {config.text_backend}")
+
+
+def _create_cache(config: MemoryConfig) -> MemoryCache:
+    """Create a memory cache.
+
+    Args:
+        config: Memory system configuration.
+
+    Returns:
+        A MemoryCache implementation.
+    """
+    from headroom.memory.adapters.cache import LRUMemoryCache
+
+    # LRUMemoryCache implements MemoryCache protocol
+    return LRUMemoryCache(max_size=config.cache_max_size)  # type: ignore[return-value]

headroom/memory/fast_store.py

@@ -1,621 +0,0 @@
-"""Fast embedding-based memory store.
-
-Sub-100ms write and read latency by:
-1. NO LLM extraction - just embed and store
-2. Vector similarity search - not keyword matching
-3. Optional local embeddings for sub-10ms latency
-
-This replaces the slow LLM-based extraction approach.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import sqlite3
-import time
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-from uuid import uuid4
-
-import numpy as np
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class MemoryChunk:
-    """A memory chunk with text and embedding."""
-
-    id: str = field(default_factory=lambda: str(uuid4()))
-    text: str = ""
-    role: str = "user"  # "user" or "assistant"
-    embedding: np.ndarray | None = None
-    timestamp: datetime = field(default_factory=datetime.utcnow)
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-    def to_dict(self) -> dict:
-        """Convert to dictionary for storage."""
-        return {
-            "id": self.id,
-            "text": self.text,
-            "role": self.role,
-            "embedding": self.embedding.tolist() if self.embedding is not None else None,
-            "timestamp": self.timestamp.isoformat(),
-            "metadata": self.metadata,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict) -> MemoryChunk:
-        """Create from dictionary."""
-        embedding = None
-        if data.get("embedding"):
-            embedding = np.array(data["embedding"], dtype=np.float32)
-        return cls(
-            id=data["id"],
-            text=data["text"],
-            role=data.get("role", "user"),
-            embedding=embedding,
-            timestamp=datetime.fromisoformat(data["timestamp"]),
-            metadata=data.get("metadata", {}),
-        )
-
-
-# Type aliases for embedding functions
-EmbedFn = Callable[[str], np.ndarray]
-BatchEmbedFn = Callable[[list[str]], list[np.ndarray]]
-
-
-def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
-    """Compute cosine similarity between two vectors."""
-    norm_a = np.linalg.norm(a)
-    norm_b = np.linalg.norm(b)
-    if norm_a == 0 or norm_b == 0:
-        return 0.0
-    return float(np.dot(a, b) / (norm_a * norm_b))
-
-
-def cosine_similarity_batch(query: np.ndarray, vectors: np.ndarray) -> np.ndarray:
-    """Compute cosine similarity between query and multiple vectors."""
-    # Normalize query
-    query_norm = query / (np.linalg.norm(query) + 1e-9)
-    # Normalize vectors
-    norms = np.linalg.norm(vectors, axis=1, keepdims=True) + 1e-9
-    vectors_norm = vectors / norms
-    # Dot product - cast to ndarray to satisfy mypy
-    result: np.ndarray = np.dot(vectors_norm, query_norm)
-    return result
-
-
-class FastMemoryStore:
-    """Fast embedding-based memory store.
-
-    Features:
-    - Sub-100ms write latency (no LLM, just embedding)
-    - Sub-50ms read latency (vector similarity search)
-    - Pluggable embedding functions (local or API)
-    - SQLite storage with in-memory vector cache
-
-    Usage:
-        store = FastMemoryStore(db_path, embed_fn=my_embed_fn)
-        store.add("user_123", "I prefer Python", role="user")
-        results = store.search("user_123", "programming language", top_k=5)
-    """
-
-    def __init__(
-        self,
-        db_path: str | Path,
-        embed_fn: EmbedFn | None = None,
-        embedding_dim: int = 1536,  # OpenAI default
-    ):
-        """Initialize the store.
-
-        Args:
-            db_path: Path to SQLite database
-            embed_fn: Function to embed text (if None, must call set_embed_fn later)
-            embedding_dim: Dimension of embeddings
-        """
-        self.db_path = Path(db_path)
-        self.embed_fn = embed_fn
-        self.embedding_dim = embedding_dim
-
-        # In-memory vector cache for fast similarity search
-        self._vector_cache: dict[
-            str, dict[str, np.ndarray]
-        ] = {}  # user_id -> {chunk_id -> embedding}
-        self._chunk_cache: dict[str, dict[str, MemoryChunk]] = {}  # user_id -> {chunk_id -> chunk}
-
-        self._init_db()
-        self._load_cache()
-
-    def _init_db(self) -> None:
-        """Initialize SQLite database."""
-        self.db_path.parent.mkdir(parents=True, exist_ok=True)
-
-        with sqlite3.connect(str(self.db_path)) as conn:
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS memory_chunks (
-                    id TEXT PRIMARY KEY,
-                    user_id TEXT NOT NULL,
-                    text TEXT NOT NULL,
-                    role TEXT DEFAULT 'user',
-                    embedding BLOB,
-                    timestamp TEXT NOT NULL,
-                    metadata TEXT DEFAULT '{}',
-                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-                )
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_chunks_user_id
-                ON memory_chunks(user_id)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_chunks_timestamp
-                ON memory_chunks(user_id, timestamp DESC)
-            """)
-            conn.commit()
-
-    def _load_cache(self) -> None:
-        """Load all embeddings into memory for fast search."""
-        with sqlite3.connect(str(self.db_path)) as conn:
-            cursor = conn.execute("""
-                SELECT id, user_id, text, role, embedding, timestamp, metadata
-                FROM memory_chunks
-                WHERE embedding IS NOT NULL
-            """)
-
-            for row in cursor:
-                chunk_id, user_id, text, role, embedding_blob, timestamp, metadata = row
-
-                if user_id not in self._vector_cache:
-                    self._vector_cache[user_id] = {}
-                    self._chunk_cache[user_id] = {}
-
-                # Deserialize embedding
-                embedding = np.frombuffer(embedding_blob, dtype=np.float32)
-
-                self._vector_cache[user_id][chunk_id] = embedding
-
-                chunk = MemoryChunk(
-                    id=chunk_id,
-                    text=text,
-                    role=role,
-                    embedding=embedding,
-                    timestamp=datetime.fromisoformat(timestamp),
-                    metadata=json.loads(metadata) if metadata else {},
-                )
-                self._chunk_cache[user_id][chunk_id] = chunk
-
-        logger.debug(f"Loaded {sum(len(v) for v in self._vector_cache.values())} chunks into cache")
-
-    def set_embed_fn(self, embed_fn: EmbedFn) -> None:
-        """Set the embedding function."""
-        self.embed_fn = embed_fn
-
-    def add(
-        self,
-        user_id: str,
-        text: str,
-        role: str = "user",
-        metadata: dict[str, Any] | None = None,
-    ) -> MemoryChunk:
-        """Add a memory chunk.
-
-        This is the FAST path - just embed and store, no LLM extraction.
-        Typical latency: <50ms with API embeddings, <10ms with local.
-
-        Args:
-            user_id: User/entity identifier
-            text: Text to store
-            role: "user" or "assistant"
-            metadata: Optional metadata
-
-        Returns:
-            The created MemoryChunk
-        """
-        if not self.embed_fn:
-            raise ValueError("No embedding function set. Call set_embed_fn() first.")
-
-        start_time = time.perf_counter()
-
-        # Embed the text
-        embedding = self.embed_fn(text)
-        embed_time = time.perf_counter() - start_time
-
-        # Create chunk
-        chunk = MemoryChunk(
-            text=text,
-            role=role,
-            embedding=embedding,
-            metadata=metadata or {},
-        )
-
-        # Store in SQLite
-        with sqlite3.connect(str(self.db_path)) as conn:
-            conn.execute(
-                """
-                INSERT INTO memory_chunks (id, user_id, text, role, embedding, timestamp, metadata)
-                VALUES (?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    chunk.id,
-                    user_id,
-                    chunk.text,
-                    chunk.role,
-                    embedding.astype(np.float32).tobytes(),
-                    chunk.timestamp.isoformat(),
-                    json.dumps(chunk.metadata),
-                ),
-            )
-            conn.commit()
-
-        # Update cache
-        if user_id not in self._vector_cache:
-            self._vector_cache[user_id] = {}
-            self._chunk_cache[user_id] = {}
-
-        self._vector_cache[user_id][chunk.id] = embedding
-        self._chunk_cache[user_id][chunk.id] = chunk
-
-        total_time = time.perf_counter() - start_time
-        logger.debug(f"Added chunk in {total_time * 1000:.1f}ms (embed: {embed_time * 1000:.1f}ms)")
-
-        return chunk
-
-    def add_turn(
-        self,
-        user_id: str,
-        user_message: str,
-        assistant_response: str,
-        metadata: dict[str, Any] | None = None,
-    ) -> tuple[MemoryChunk, MemoryChunk]:
-        """Add a conversation turn (user message + assistant response).
-
-        Convenience method that stores both parts of a turn.
-
-        Args:
-            user_id: User/entity identifier
-            user_message: The user's message
-            assistant_response: The assistant's response
-            metadata: Optional metadata for both chunks
-
-        Returns:
-            Tuple of (user_chunk, assistant_chunk)
-        """
-        user_chunk = self.add(user_id, user_message, role="user", metadata=metadata)
-        assistant_chunk = self.add(user_id, assistant_response, role="assistant", metadata=metadata)
-        return user_chunk, assistant_chunk
-
-    def add_turn_batched(
-        self,
-        user_id: str,
-        user_message: str,
-        assistant_response: str,
-        batch_embed_fn: BatchEmbedFn,
-        metadata: dict[str, Any] | None = None,
-    ) -> tuple[MemoryChunk, MemoryChunk]:
-        """Add a conversation turn using BATCHED embedding (single API call).
-
-        This is the FASTEST path - embeds both messages in ONE API call.
-        Typical latency: 50-100ms total vs 200-400ms with individual calls.
-
-        Args:
-            user_id: User/entity identifier
-            user_message: The user's message
-            assistant_response: The assistant's response
-            batch_embed_fn: Batch embedding function
-            metadata: Optional metadata for both chunks
-
-        Returns:
-            Tuple of (user_chunk, assistant_chunk)
-        """
-        start_time = time.perf_counter()
-
-        # Embed BOTH messages in ONE API call
-        embeddings = batch_embed_fn([user_message, assistant_response])
-        embed_time = time.perf_counter() - start_time
-
-        # Create chunks
-        user_chunk = MemoryChunk(
-            text=user_message,
-            role="user",
-            embedding=embeddings[0],
-            metadata=metadata or {},
-        )
-        assistant_chunk = MemoryChunk(
-            text=assistant_response,
-            role="assistant",
-            embedding=embeddings[1],
-            metadata=metadata or {},
-        )
-
-        # Store in SQLite (batch insert)
-        with sqlite3.connect(str(self.db_path)) as conn:
-            conn.executemany(
-                """
-                INSERT INTO memory_chunks (id, user_id, text, role, embedding, timestamp, metadata)
-                VALUES (?, ?, ?, ?, ?, ?, ?)
-                """,
-                [
-                    (
-                        user_chunk.id,
-                        user_id,
-                        user_chunk.text,
-                        user_chunk.role,
-                        embeddings[0].astype(np.float32).tobytes(),
-                        user_chunk.timestamp.isoformat(),
-                        json.dumps(user_chunk.metadata),
-                    ),
-                    (
-                        assistant_chunk.id,
-                        user_id,
-                        assistant_chunk.text,
-                        assistant_chunk.role,
-                        embeddings[1].astype(np.float32).tobytes(),
-                        assistant_chunk.timestamp.isoformat(),
-                        json.dumps(assistant_chunk.metadata),
-                    ),
-                ],
-            )
-            conn.commit()
-
-        # Update cache
-        if user_id not in self._vector_cache:
-            self._vector_cache[user_id] = {}
-            self._chunk_cache[user_id] = {}
-
-        self._vector_cache[user_id][user_chunk.id] = embeddings[0]
-        self._vector_cache[user_id][assistant_chunk.id] = embeddings[1]
-        self._chunk_cache[user_id][user_chunk.id] = user_chunk
-        self._chunk_cache[user_id][assistant_chunk.id] = assistant_chunk
-
-        total_time = time.perf_counter() - start_time
-        logger.debug(
-            f"Added turn (batched) in {total_time * 1000:.1f}ms (embed: {embed_time * 1000:.1f}ms)"
-        )
-
-        return user_chunk, assistant_chunk
-
-    def search(
-        self,
-        user_id: str,
-        query: str,
-        top_k: int = 5,
-        min_similarity: float = 0.0,
-        role_filter: str | None = None,
-    ) -> list[tuple[MemoryChunk, float]]:
-        """Search for relevant memory chunks.
-
-        Uses vector similarity search for semantic matching.
-        Typical latency: <50ms with API embeddings, <10ms with local.
-
-        Args:
-            user_id: User/entity identifier
-            query: Search query
-            top_k: Number of results to return
-            min_similarity: Minimum cosine similarity threshold
-            role_filter: Optional filter by role ("user" or "assistant")
-
-        Returns:
-            List of (chunk, similarity_score) tuples, sorted by relevance
-        """
-        if not self.embed_fn:
-            raise ValueError("No embedding function set. Call set_embed_fn() first.")
-
-        start_time = time.perf_counter()
-
-        # Check if user has any memories
-        if user_id not in self._vector_cache or not self._vector_cache[user_id]:
-            return []
-
-        # Embed query
-        query_embedding = self.embed_fn(query)
-        embed_time = time.perf_counter() - start_time
-
-        # Get user's vectors
-        chunk_ids = list(self._vector_cache[user_id].keys())
-        vectors = np.array([self._vector_cache[user_id][cid] for cid in chunk_ids])
-
-        # Compute similarities
-        similarities = cosine_similarity_batch(query_embedding, vectors)
-        search_time = time.perf_counter() - start_time - embed_time
-
-        # Sort by similarity
-        sorted_indices = np.argsort(similarities)[::-1]
-
-        # Collect results
-        results = []
-        for idx in sorted_indices:
-            chunk_id = chunk_ids[idx]
-            similarity = float(similarities[idx])
-
-            if similarity < min_similarity:
-                break
-
-            chunk = self._chunk_cache[user_id][chunk_id]
-
-            # Apply role filter
-            if role_filter and chunk.role != role_filter:
-                continue
-
-            results.append((chunk, similarity))
-
-            if len(results) >= top_k:
-                break
-
-        total_time = time.perf_counter() - start_time
-        logger.debug(
-            f"Search completed in {total_time * 1000:.1f}ms "
-            f"(embed: {embed_time * 1000:.1f}ms, search: {search_time * 1000:.1f}ms)"
-        )
-
-        return results
-
-    def get_recent(
-        self,
-        user_id: str,
-        limit: int = 10,
-        role_filter: str | None = None,
-    ) -> list[MemoryChunk]:
-        """Get recent memory chunks.
-
-        Args:
-            user_id: User/entity identifier
-            limit: Maximum number of chunks to return
-            role_filter: Optional filter by role
-
-        Returns:
-            List of chunks, sorted by timestamp (newest first)
-        """
-        if user_id not in self._chunk_cache:
-            return []
-
-        chunks = list(self._chunk_cache[user_id].values())
-
-        # Apply role filter
-        if role_filter:
-            chunks = [c for c in chunks if c.role == role_filter]
-
-        # Sort by timestamp
-        chunks.sort(key=lambda c: c.timestamp, reverse=True)
-
-        return chunks[:limit]
-
-    def get_all(self, user_id: str) -> list[MemoryChunk]:
-        """Get all memory chunks for a user."""
-        if user_id not in self._chunk_cache:
-            return []
-        return list(self._chunk_cache[user_id].values())
-
-    def delete(self, user_id: str, chunk_id: str) -> bool:
-        """Delete a specific chunk."""
-        with sqlite3.connect(str(self.db_path)) as conn:
-            cursor = conn.execute(
-                "DELETE FROM memory_chunks WHERE id = ? AND user_id = ?",
-                (chunk_id, user_id),
-            )
-            conn.commit()
-            deleted = cursor.rowcount > 0
-
-        if deleted and user_id in self._vector_cache:
-            self._vector_cache[user_id].pop(chunk_id, None)
-            self._chunk_cache[user_id].pop(chunk_id, None)
-
-        return deleted
-
-    def clear(self, user_id: str) -> int:
-        """Clear all memories for a user."""
-        with sqlite3.connect(str(self.db_path)) as conn:
-            cursor = conn.execute(
-                "DELETE FROM memory_chunks WHERE user_id = ?",
-                (user_id,),
-            )
-            conn.commit()
-            count = cursor.rowcount
-
-        self._vector_cache.pop(user_id, None)
-        self._chunk_cache.pop(user_id, None)
-
-        return count
-
-    def stats(self, user_id: str) -> dict[str, Any]:
-        """Get statistics for a user."""
-        chunks = self.get_all(user_id)
-        return {
-            "total": len(chunks),
-            "user_messages": sum(1 for c in chunks if c.role == "user"),
-            "assistant_messages": sum(1 for c in chunks if c.role == "assistant"),
-        }
-
-
-# =============================================================================
-# Embedding Functions
-# =============================================================================
-
-
-def create_openai_embed_fn(
-    client: Any,
-    model: str = "text-embedding-3-small",
-) -> EmbedFn:
-    """Create an embedding function using OpenAI API.
-
-    Typical latency: 30-100ms per call.
-
-    Args:
-        client: OpenAI client
-        model: Embedding model to use
-
-    Returns:
-        Embedding function
-    """
-
-    def embed(text: str) -> np.ndarray:
-        response = client.embeddings.create(
-            model=model,
-            input=text,
-        )
-        return np.array(response.data[0].embedding, dtype=np.float32)
-
-    return embed
-
-
-def create_openai_batch_embed_fn(
-    client: Any,
-    model: str = "text-embedding-3-small",
-) -> BatchEmbedFn:
-    """Create a BATCH embedding function using OpenAI API.
-
-    Much faster than individual calls - single API round trip for multiple texts.
-    Typical latency: 50-200ms for 10 texts vs 500-2000ms for 10 individual calls.
-
-    Args:
-        client: OpenAI client
-        model: Embedding model to use
-
-    Returns:
-        Batch embedding function
-    """
-
-    def embed_batch(texts: list[str]) -> list[np.ndarray]:
-        if not texts:
-            return []
-        response = client.embeddings.create(
-            model=model,
-            input=texts,
-        )
-        # Sort by index to maintain order
-        sorted_data = sorted(response.data, key=lambda x: x.index)
-        return [np.array(d.embedding, dtype=np.float32) for d in sorted_data]
-
-    return embed_batch
-
-
-def create_local_embed_fn(
-    model_name: str = "all-MiniLM-L6-v2",
-) -> EmbedFn:
-    """Create an embedding function using local sentence-transformers.
-
-    Typical latency: 5-20ms per call (after model load).
-
-    Args:
-        model_name: Sentence-transformers model name
-
-    Returns:
-        Embedding function
-    """
-    try:
-        from sentence_transformers import SentenceTransformer
-    except ImportError:
-        raise ImportError(
-            "sentence-transformers not installed. Install with: pip install sentence-transformers"
-        ) from None
-
-    model = SentenceTransformer(model_name)
-
-    def embed(text: str) -> np.ndarray:
-        return model.encode(text, convert_to_numpy=True).astype(np.float32)
-
-    return embed

headroom/memory/fast_wrapper.py

@@ -1,311 +0,0 @@
-"""Fast Memory Wrapper - Zero-latency inline extraction + semantic retrieval.
-
-This is the ultimate memory solution:
-1. ZERO extra latency - memories extracted as part of LLM response (Letta-style)
-2. Semantic retrieval - vector similarity for intelligent memory lookup
-3. Local embeddings - sub-50ms retrieval, no API calls needed
-
-Usage:
-    from headroom.memory import with_fast_memory
-
-    client = with_fast_memory(OpenAI(), user_id="alice")
-    response = client.chat.completions.create(
-        model="gpt-4o",
-        messages=[{"role": "user", "content": "I prefer Python"}]
-    )
-    # Memory extracted INLINE - zero extra latency!
-"""
-
-from __future__ import annotations
-
-import copy
-from pathlib import Path
-from typing import Any
-
-from headroom.memory.fast_store import (
-    FastMemoryStore,
-    MemoryChunk,
-    create_local_embed_fn,
-    create_openai_embed_fn,
-)
-from headroom.memory.inline_extractor import (
-    inject_memory_instruction,
-    parse_response_with_memory,
-)
-
-
-class FastMemoryWrapper:
-    """Wraps an LLM client with zero-latency inline memory extraction.
-
-    Architecture:
-    1. BEFORE: Inject relevant memories into user message (semantic search)
-    2. DURING: Memory instruction is in system prompt
-    3. AFTER: Parse memory block from response, store extracted memories
-
-    All memory operations happen as part of the normal LLM flow - no extra calls!
-    """
-
-    def __init__(
-        self,
-        client: Any,
-        user_id: str,
-        db_path: str | Path = "headroom_fast_memory.db",
-        top_k: int = 5,
-        use_local_embeddings: bool = True,
-        embedding_model: str = "all-MiniLM-L6-v2",
-        _store: FastMemoryStore | None = None,
-    ):
-        """Initialize the fast memory wrapper.
-
-        Args:
-            client: OpenAI-compatible LLM client
-            user_id: User identifier for memory isolation
-            db_path: Path to SQLite database
-            top_k: Number of memories to inject
-            use_local_embeddings: Use local model (fast) or OpenAI API
-            embedding_model: Model name for local embeddings
-            _store: Override store (for testing)
-        """
-        self._client = client
-        self._user_id = user_id
-        self._top_k = top_k
-
-        # Initialize store with appropriate embedding function
-        if _store:
-            self._store = _store
-        elif use_local_embeddings:
-            embed_fn = create_local_embed_fn(embedding_model)
-            # MiniLM-L6-v2 produces 384-dim embeddings
-            self._store = FastMemoryStore(db_path, embed_fn=embed_fn, embedding_dim=384)
-        else:
-            embed_fn = create_openai_embed_fn(client)
-            self._store = FastMemoryStore(db_path, embed_fn=embed_fn)
-
-        # Create wrapped chat interface
-        self.chat = _FastWrappedChat(self)
-
-    @property
-    def memory(self) -> _FastMemoryAPI:
-        """Direct access to memory operations."""
-        return _FastMemoryAPI(self._store, self._user_id)
-
-    def _inject_memories(self, messages: list[dict]) -> list[dict]:
-        """Inject relevant memories into user message.
-
-        Uses semantic search (vector similarity) to find relevant memories.
-        Injects into FIRST user message to preserve system prompt caching.
-
-        Args:
-            messages: Original messages list
-
-        Returns:
-            New messages with memories injected
-        """
-        # Find the last user message for search context
-        user_content = None
-        for msg in reversed(messages):
-            if msg.get("role") == "user":
-                user_content = msg.get("content", "")
-                break
-
-        if not user_content:
-            return messages
-
-        # Semantic search for relevant memories
-        results = self._store.search(self._user_id, str(user_content), top_k=self._top_k)
-
-        if not results:
-            return messages
-
-        # Build context block
-        context_lines = ["<context>"]
-        for chunk, _score in results:
-            context_lines.append(f"- {chunk.text}")
-        context_lines.append("</context>")
-        context_block = "\n".join(context_lines)
-
-        # Inject into first user message
-        new_messages = copy.deepcopy(messages)
-        for msg in new_messages:
-            if msg.get("role") == "user":
-                original = msg.get("content", "")
-                msg["content"] = f"{context_block}\n\n{original}"
-                break
-
-        return new_messages
-
-    def _store_memories(self, memories: list[dict[str, Any]]) -> None:
-        """Store extracted memories.
-
-        Args:
-            memories: List of memory dicts from inline extraction
-        """
-        for mem in memories:
-            content = mem.get("content", "")
-            category = mem.get("category", "fact")
-            if content:
-                self._store.add(
-                    self._user_id,
-                    content,
-                    role="memory",
-                    metadata={"category": category, "source": "inline_extraction"},
-                )
-
-
-class _FastWrappedChat:
-    """Wrapped chat interface."""
-
-    def __init__(self, wrapper: FastMemoryWrapper):
-        self._wrapper = wrapper
-        self.completions = _FastWrappedCompletions(wrapper)
-
-
-class _FastWrappedCompletions:
-    """Wrapped completions with inline memory extraction."""
-
-    def __init__(self, wrapper: FastMemoryWrapper):
-        self._wrapper = wrapper
-
-    def create(self, **kwargs: Any) -> Any:
-        """Create chat completion with inline memory extraction.
-
-        Flow:
-        1. Search for relevant memories (semantic)
-        2. Inject memories into user message
-        3. Add memory instruction to system prompt
-        4. Forward to LLM
-        5. Parse response to extract memories
-        6. Store extracted memories
-        7. Return clean response (without memory block)
-        """
-        messages = kwargs.get("messages", [])
-
-        # 1. Inject relevant memories into user message
-        enhanced_messages = self._wrapper._inject_memories(messages)
-
-        # 2. Add memory extraction instruction to system prompt
-        enhanced_messages = inject_memory_instruction(enhanced_messages, short=True)
-        kwargs["messages"] = enhanced_messages
-
-        # 3. Forward to LLM
-        response = self._wrapper._client.chat.completions.create(**kwargs)
-
-        # 4. Parse response and extract memories
-        raw_content = response.choices[0].message.content
-        parsed = parse_response_with_memory(raw_content)
-
-        # 5. Store extracted memories
-        if parsed.memories:
-            self._wrapper._store_memories(parsed.memories)
-
-        # 6. Return clean response (modify in place)
-        response.choices[0].message.content = parsed.content
-
-        return response
-
-
-class _FastMemoryAPI:
-    """Direct API for memory operations."""
-
-    def __init__(self, store: FastMemoryStore, user_id: str):
-        self._store = store
-        self._user_id = user_id
-
-    def search(self, query: str, top_k: int = 5) -> list[tuple[MemoryChunk, float]]:
-        """Semantic search for memories.
-
-        Args:
-            query: Search query
-            top_k: Max results
-
-        Returns:
-            List of (memory, similarity_score) tuples
-        """
-        return self._store.search(self._user_id, query, top_k)
-
-    def add(self, content: str, category: str = "fact") -> MemoryChunk:
-        """Manually add a memory.
-
-        Args:
-            content: Memory content
-            category: preference, fact, or context
-
-        Returns:
-            The created memory chunk
-        """
-        return self._store.add(
-            self._user_id,
-            content,
-            role="memory",
-            metadata={"category": category, "source": "manual"},
-        )
-
-    def get_all(self) -> list[MemoryChunk]:
-        """Get all memories for this user."""
-        return self._store.get_all(self._user_id)
-
-    def clear(self) -> int:
-        """Clear all memories for this user."""
-        return self._store.clear(self._user_id)
-
-    def stats(self) -> dict:
-        """Get memory statistics."""
-        return self._store.stats(self._user_id)
-
-
-def with_fast_memory(
-    client: Any,
-    user_id: str,
-    db_path: str | Path = "headroom_fast_memory.db",
-    top_k: int = 5,
-    use_local_embeddings: bool = True,
-    embedding_model: str = "all-MiniLM-L6-v2",
-    **kwargs: Any,
-) -> FastMemoryWrapper:
-    """Wrap an LLM client with zero-latency inline memory extraction.
-
-    This is the fastest memory solution:
-    1. ZERO extra LLM calls - memories extracted inline as part of response
-    2. Sub-50ms retrieval - local embeddings, no API calls
-    3. Semantic search - finds conceptually related memories
-
-    Args:
-        client: OpenAI-compatible LLM client
-        user_id: User identifier for memory isolation
-        db_path: Path to SQLite database
-        top_k: Number of memories to inject per request
-        use_local_embeddings: Use local model (True) or OpenAI API (False)
-        embedding_model: Model name for local embeddings
-        **kwargs: Additional arguments
-
-    Returns:
-        Wrapped client with automatic memory
-
-    Example:
-        from openai import OpenAI
-        from headroom.memory import with_fast_memory
-
-        client = with_fast_memory(OpenAI(), user_id="alice")
-
-        # First conversation - memory extracted INLINE
-        response = client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "I prefer Python for backend work"}]
-        )
-
-        # Later - memories automatically retrieved
-        response = client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "What language should I use?"}]
-        )
-        # User sees: "Based on your preference for Python..."
-    """
-    return FastMemoryWrapper(
-        client=client,
-        user_id=user_id,
-        db_path=db_path,
-        top_k=top_k,
-        use_local_embeddings=use_local_embeddings,
-        embedding_model=embedding_model,
-        **kwargs,
-    )

headroom/memory/models.py

@@ -0,0 +1,149 @@
+"""Hierarchical memory data models for Headroom."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+import numpy as np
+
+
+class ScopeLevel(Enum):
+    """Memory scope hierarchy levels."""
+
+    USER = "user"  # Persistent across all sessions
+    SESSION = "session"  # Persistent within a task/conversation
+    AGENT = "agent"  # Persistent within an agent's lifetime
+    TURN = "turn"  # Ephemeral, single LLM call
+
+
+class MemoryCategory(Enum):
+    """Memory classification categories."""
+
+    PREFERENCE = "preference"  # User preferences ("likes Rust")
+    FACT = "fact"  # Factual information ("auth is in src/")
+    CONTEXT = "context"  # Contextual info ("working on CLI tool")
+    ENTITY = "entity"  # Entity reference ("John from team X")
+    DECISION = "decision"  # Decisions made ("chose OAuth over JWT")
+    INSIGHT = "insight"  # Derived insights ("user is senior dev")
+
+
+@dataclass
+class Memory:
+    """A hierarchically-scoped memory with temporal awareness."""
+
+    # Identity
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    content: str = ""
+
+    # Hierarchical Scoping (required: user_id, optional: narrower scopes)
+    user_id: str = ""
+    session_id: str | None = None
+    agent_id: str | None = None
+    turn_id: str | None = None
+
+    # Temporal
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    valid_from: datetime = field(default_factory=datetime.utcnow)
+    valid_until: datetime | None = None  # None = current/active
+
+    # Classification
+    category: MemoryCategory = MemoryCategory.FACT
+    importance: float = 0.5  # 0.0 - 1.0
+
+    # Lineage (for supersession and bubbling)
+    supersedes: str | None = None  # ID of memory this replaced
+    superseded_by: str | None = None  # ID of memory that replaced this
+    promoted_from: str | None = None  # ID of child memory (if bubbled up)
+    promotion_chain: list[str] = field(default_factory=list)
+
+    # Access tracking
+    access_count: int = 0
+    last_accessed: datetime | None = None
+
+    # Entity references
+    entity_refs: list[str] = field(default_factory=list)
+
+    # Embedding (for vector search)
+    embedding: np.ndarray | None = None
+
+    # Metadata
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def scope_level(self) -> ScopeLevel:
+        """Compute the scope level from hierarchy fields."""
+        if self.turn_id is not None:
+            return ScopeLevel.TURN
+        if self.agent_id is not None:
+            return ScopeLevel.AGENT
+        if self.session_id is not None:
+            return ScopeLevel.SESSION
+        return ScopeLevel.USER
+
+    @property
+    def is_current(self) -> bool:
+        """Check if this memory is current (not superseded)."""
+        return self.valid_until is None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "content": self.content,
+            "user_id": self.user_id,
+            "session_id": self.session_id,
+            "agent_id": self.agent_id,
+            "turn_id": self.turn_id,
+            "created_at": self.created_at.isoformat(),
+            "valid_from": self.valid_from.isoformat(),
+            "valid_until": self.valid_until.isoformat() if self.valid_until else None,
+            "category": self.category.value,
+            "importance": self.importance,
+            "supersedes": self.supersedes,
+            "superseded_by": self.superseded_by,
+            "promoted_from": self.promoted_from,
+            "promotion_chain": self.promotion_chain,
+            "access_count": self.access_count,
+            "last_accessed": self.last_accessed.isoformat() if self.last_accessed else None,
+            "entity_refs": self.entity_refs,
+            "embedding": self.embedding.tolist() if self.embedding is not None else None,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Memory:
+        """Create from dictionary."""
+        embedding = None
+        if data.get("embedding"):
+            embedding = np.array(data["embedding"], dtype=np.float32)
+
+        return cls(
+            id=data["id"],
+            content=data["content"],
+            user_id=data["user_id"],
+            session_id=data.get("session_id"),
+            agent_id=data.get("agent_id"),
+            turn_id=data.get("turn_id"),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            valid_from=datetime.fromisoformat(data["valid_from"]),
+            valid_until=datetime.fromisoformat(data["valid_until"])
+            if data.get("valid_until")
+            else None,
+            category=MemoryCategory(data["category"]),
+            importance=data["importance"],
+            supersedes=data.get("supersedes"),
+            superseded_by=data.get("superseded_by"),
+            promoted_from=data.get("promoted_from"),
+            promotion_chain=data.get("promotion_chain", []),
+            access_count=data.get("access_count", 0),
+            last_accessed=datetime.fromisoformat(data["last_accessed"])
+            if data.get("last_accessed")
+            else None,
+            entity_refs=data.get("entity_refs", []),
+            embedding=embedding,
+            metadata=data.get("metadata", {}),
+        )

headroom/memory/ports.py

@@ -0,0 +1,664 @@
+"""Protocol interfaces for pluggable memory system components."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+
+from headroom.memory.models import Memory, MemoryCategory, ScopeLevel
+
+# =============================================================================
+# Filter Dataclasses
+# =============================================================================
+
+
+@dataclass
+class MemoryFilter:
+    """Filter criteria for memory store queries."""
+
+    # Scope filters
+    user_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    turn_id: str | None = None
+    scope_levels: list[ScopeLevel] | None = None
+
+    # Category filters
+    categories: list[MemoryCategory] | None = None
+
+    # Temporal filters
+    created_after: datetime | None = None
+    created_before: datetime | None = None
+    valid_at: datetime | None = None  # Point-in-time query
+    include_superseded: bool = False  # Include historical versions
+
+    # Importance filters
+    min_importance: float | None = None
+    max_importance: float | None = None
+
+    # Entity filters
+    entity_refs: list[str] | None = None  # Any of these entities
+
+    # Lineage filters
+    has_supersedes: bool | None = None
+    has_promoted_from: bool | None = None
+
+    # Pagination
+    limit: int | None = None
+    offset: int = 0
+
+    # Sorting
+    order_by: str = "created_at"  # created_at, importance, access_count, last_accessed
+    order_desc: bool = True
+
+    # Metadata filters
+    metadata_filters: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VectorFilter:
+    """Filter criteria for vector similarity searches."""
+
+    # Required: query vector or text (one must be provided)
+    query_vector: np.ndarray | None = None
+    query_text: str | None = None  # Will be embedded if vector not provided
+
+    # Search parameters
+    top_k: int = 10
+    min_similarity: float = 0.0  # Minimum cosine similarity threshold
+
+    # Scope filters (inherited from MemoryFilter)
+    user_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    scope_levels: list[ScopeLevel] | None = None
+
+    # Category filters
+    categories: list[MemoryCategory] | None = None
+
+    # Temporal filters
+    valid_at: datetime | None = None
+    include_superseded: bool = False
+
+    # Entity filters
+    entity_refs: list[str] | None = None
+
+    # Metadata filters
+    metadata_filters: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TextFilter:
+    """Filter criteria for full-text searches."""
+
+    # Required: search query
+    query: str = ""
+
+    # Search mode
+    match_mode: str = "contains"  # contains, prefix, exact, fuzzy, regex
+    case_sensitive: bool = False
+
+    # Result parameters
+    limit: int = 100
+
+    # Scope filters (inherited from MemoryFilter)
+    user_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    scope_levels: list[ScopeLevel] | None = None
+
+    # Category filters
+    categories: list[MemoryCategory] | None = None
+
+    # Temporal filters
+    valid_at: datetime | None = None
+    include_superseded: bool = False
+
+    # Metadata filters
+    metadata_filters: dict[str, Any] = field(default_factory=dict)
+
+
+# =============================================================================
+# Search Result Dataclasses
+# =============================================================================
+
+
+@dataclass
+class VectorSearchResult:
+    """Result from a vector similarity search."""
+
+    memory: Memory
+    similarity: float  # Cosine similarity score (0.0 - 1.0)
+    rank: int  # Position in results (1-indexed)
+
+    def __lt__(self, other: VectorSearchResult) -> bool:
+        """Enable sorting by similarity (descending)."""
+        return self.similarity > other.similarity
+
+
+@dataclass
+class TextSearchResult:
+    """Result from a full-text search."""
+
+    memory: Memory
+    score: float  # Relevance score (implementation-specific)
+    rank: int  # Position in results (1-indexed)
+    highlights: list[str] = field(default_factory=list)  # Matching snippets
+    matched_terms: list[str] = field(default_factory=list)  # Terms that matched
+
+    def __lt__(self, other: TextSearchResult) -> bool:
+        """Enable sorting by score (descending)."""
+        return self.score > other.score
+
+
+# =============================================================================
+# Protocol Interfaces
+# =============================================================================
+
+
+@runtime_checkable
+class MemoryStore(Protocol):
+    """
+    Protocol for memory persistence backends.
+
+    Implementations handle CRUD operations and filtering for Memory objects.
+    Examples: SQLite, PostgreSQL, DynamoDB, Redis, in-memory.
+    """
+
+    async def save(self, memory: Memory) -> None:
+        """
+        Save or update a memory.
+
+        If a memory with the same ID exists, it will be updated.
+
+        Args:
+            memory: The memory to save.
+        """
+        ...
+
+    async def save_batch(self, memories: list[Memory]) -> None:
+        """
+        Save multiple memories in a single operation.
+
+        Args:
+            memories: List of memories to save.
+        """
+        ...
+
+    async def get(self, memory_id: str) -> Memory | None:
+        """
+        Retrieve a memory by ID.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            The memory if found, None otherwise.
+        """
+        ...
+
+    async def get_batch(self, memory_ids: list[str]) -> list[Memory]:
+        """
+        Retrieve multiple memories by ID.
+
+        Args:
+            memory_ids: List of memory IDs to retrieve.
+
+        Returns:
+            List of found memories (may be shorter than input if some not found).
+        """
+        ...
+
+    async def delete(self, memory_id: str) -> bool:
+        """
+        Delete a memory by ID.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if the memory was deleted, False if not found.
+        """
+        ...
+
+    async def delete_batch(self, memory_ids: list[str]) -> int:
+        """
+        Delete multiple memories by ID.
+
+        Args:
+            memory_ids: List of memory IDs to delete.
+
+        Returns:
+            Number of memories actually deleted.
+        """
+        ...
+
+    async def query(self, filter: MemoryFilter) -> list[Memory]:
+        """
+        Query memories matching the given filter.
+
+        Args:
+            filter: Filter criteria for the query.
+
+        Returns:
+            List of matching memories.
+        """
+        ...
+
+    async def count(self, filter: MemoryFilter) -> int:
+        """
+        Count memories matching the given filter.
+
+        Args:
+            filter: Filter criteria for the count.
+
+        Returns:
+            Number of matching memories.
+        """
+        ...
+
+    async def supersede(
+        self,
+        old_memory_id: str,
+        new_memory: Memory,
+        supersede_time: datetime | None = None,
+    ) -> Memory:
+        """
+        Supersede an existing memory with a new version.
+
+        This creates a temporal chain: the old memory's valid_until is set,
+        and the new memory's supersedes field points to the old one.
+
+        Args:
+            old_memory_id: ID of the memory to supersede.
+            new_memory: The new memory that replaces it.
+            supersede_time: When the supersession occurred (defaults to now).
+
+        Returns:
+            The saved new memory with lineage fields populated.
+        """
+        ...
+
+    async def get_history(
+        self,
+        memory_id: str,
+        include_future: bool = False,
+    ) -> list[Memory]:
+        """
+        Get the full history chain for a memory.
+
+        Follows the supersedes/superseded_by chain to return all versions.
+
+        Args:
+            memory_id: ID of any memory in the chain.
+            include_future: Whether to include memories that superseded this one.
+
+        Returns:
+            List of memories in temporal order (oldest first).
+        """
+        ...
+
+    async def clear_scope(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        turn_id: str | None = None,
+    ) -> int:
+        """
+        Clear all memories at or below a scope level.
+
+        Args:
+            user_id: Required user scope.
+            session_id: If provided, clear session and below.
+            agent_id: If provided, clear agent and below.
+            turn_id: If provided, clear only that turn.
+
+        Returns:
+            Number of memories deleted.
+        """
+        ...
+
+
+@runtime_checkable
+class VectorIndex(Protocol):
+    """
+    Protocol for vector similarity search backends.
+
+    Implementations handle embedding storage and similarity search.
+    Examples: FAISS, Annoy, Pinecone, Weaviate, Qdrant.
+    """
+
+    async def index(self, memory: Memory) -> None:
+        """
+        Index a memory's embedding for similarity search.
+
+        The memory must have an embedding set.
+
+        Args:
+            memory: The memory to index.
+
+        Raises:
+            ValueError: If the memory has no embedding.
+        """
+        ...
+
+    async def index_batch(self, memories: list[Memory]) -> int:
+        """
+        Index multiple memories' embeddings.
+
+        Memories without embeddings are skipped.
+
+        Args:
+            memories: List of memories to index.
+
+        Returns:
+            Number of memories actually indexed.
+        """
+        ...
+
+    async def remove(self, memory_id: str) -> bool:
+        """
+        Remove a memory from the vector index.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        ...
+
+    async def remove_batch(self, memory_ids: list[str]) -> int:
+        """
+        Remove multiple memories from the vector index.
+
+        Args:
+            memory_ids: List of memory IDs to remove.
+
+        Returns:
+            Number of memories actually removed.
+        """
+        ...
+
+    async def search(self, filter: VectorFilter) -> list[VectorSearchResult]:
+        """
+        Search for similar memories using vector similarity.
+
+        Args:
+            filter: Vector search filter with query and constraints.
+
+        Returns:
+            List of search results sorted by similarity (descending).
+        """
+        ...
+
+    async def update_embedding(self, memory_id: str, embedding: np.ndarray) -> bool:
+        """
+        Update the embedding for an indexed memory.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+            embedding: The new embedding vector.
+
+        Returns:
+            True if updated, False if memory not found in index.
+        """
+        ...
+
+    @property
+    def dimension(self) -> int:
+        """Return the embedding dimension this index expects."""
+        ...
+
+    @property
+    def size(self) -> int:
+        """Return the number of vectors currently indexed."""
+        ...
+
+
+@runtime_checkable
+class TextIndex(Protocol):
+    """
+    Protocol for full-text search backends.
+
+    Implementations handle text indexing and keyword search.
+    Examples: SQLite FTS5, Elasticsearch, Tantivy, in-memory.
+    """
+
+    async def index(self, memory: Memory) -> None:
+        """
+        Index a memory's content for full-text search.
+
+        Args:
+            memory: The memory to index.
+        """
+        ...
+
+    async def index_batch(self, memories: list[Memory]) -> int:
+        """
+        Index multiple memories for full-text search.
+
+        Args:
+            memories: List of memories to index.
+
+        Returns:
+            Number of memories actually indexed.
+        """
+        ...
+
+    async def remove(self, memory_id: str) -> bool:
+        """
+        Remove a memory from the text index.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        ...
+
+    async def remove_batch(self, memory_ids: list[str]) -> int:
+        """
+        Remove multiple memories from the text index.
+
+        Args:
+            memory_ids: List of memory IDs to remove.
+
+        Returns:
+            Number of memories actually removed.
+        """
+        ...
+
+    async def search(self, filter: TextFilter) -> list[TextSearchResult]:
+        """
+        Search for memories using full-text search.
+
+        Args:
+            filter: Text search filter with query and constraints.
+
+        Returns:
+            List of search results sorted by relevance.
+        """
+        ...
+
+    async def update_content(self, memory_id: str, content: str) -> bool:
+        """
+        Update the indexed content for a memory.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+            content: The new content to index.
+
+        Returns:
+            True if updated, False if memory not found in index.
+        """
+        ...
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """
+    Protocol for text embedding generation.
+
+    Implementations convert text to dense vector representations.
+    Examples: OpenAI embeddings, sentence-transformers, Cohere.
+    """
+
+    async def embed(self, text: str) -> np.ndarray:
+        """
+        Generate an embedding for a single text.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            The embedding vector as a numpy array.
+        """
+        ...
+
+    async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
+        """
+        Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of embedding vectors.
+        """
+        ...
+
+    @property
+    def dimension(self) -> int:
+        """Return the dimension of generated embeddings."""
+        ...
+
+    @property
+    def model_name(self) -> str:
+        """Return the name/identifier of the embedding model."""
+        ...
+
+    @property
+    def max_tokens(self) -> int:
+        """Return the maximum number of tokens the model can process."""
+        ...
+
+
+@runtime_checkable
+class MemoryCache(Protocol):
+    """
+    Protocol for memory caching layer.
+
+    Implementations provide fast access to frequently-used memories.
+    Examples: LRU cache, Redis, in-memory dict with TTL.
+    """
+
+    async def get(self, memory_id: str) -> Memory | None:
+        """
+        Get a memory from cache.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            The cached memory if found, None otherwise.
+        """
+        ...
+
+    async def get_batch(self, memory_ids: list[str]) -> dict[str, Memory]:
+        """
+        Get multiple memories from cache.
+
+        Args:
+            memory_ids: List of memory IDs to retrieve.
+
+        Returns:
+            Dict mapping found memory IDs to their memories.
+        """
+        ...
+
+    async def put(self, memory: Memory, ttl_seconds: int | None = None) -> None:
+        """
+        Put a memory in cache.
+
+        Args:
+            memory: The memory to cache.
+            ttl_seconds: Optional time-to-live in seconds.
+        """
+        ...
+
+    async def put_batch(
+        self,
+        memories: list[Memory],
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """
+        Put multiple memories in cache.
+
+        Args:
+            memories: List of memories to cache.
+            ttl_seconds: Optional time-to-live in seconds.
+        """
+        ...
+
+    async def invalidate(self, memory_id: str) -> bool:
+        """
+        Invalidate (remove) a memory from cache.
+
+        Args:
+            memory_id: The unique identifier of the memory.
+
+        Returns:
+            True if the memory was in cache, False otherwise.
+        """
+        ...
+
+    async def invalidate_batch(self, memory_ids: list[str]) -> int:
+        """
+        Invalidate multiple memories from cache.
+
+        Args:
+            memory_ids: List of memory IDs to invalidate.
+
+        Returns:
+            Number of memories that were in cache.
+        """
+        ...
+
+    async def invalidate_scope(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> int:
+        """
+        Invalidate all cached memories at or below a scope.
+
+        Args:
+            user_id: Required user scope.
+            session_id: If provided, invalidate session and below.
+            agent_id: If provided, invalidate agent and below.
+
+        Returns:
+            Number of memories invalidated.
+        """
+        ...
+
+    async def clear(self) -> None:
+        """Clear all entries from the cache."""
+        ...
+
+    @property
+    def size(self) -> int:
+        """Return the current number of cached entries."""
+        ...
+
+    @property
+    def max_size(self) -> int | None:
+        """Return the maximum cache size, or None if unbounded."""
+        ...

headroom/memory/store.py

@@ -1,434 +0,0 @@
-"""SQLite + FTS5 memory storage for Headroom Memory.
-
-Simple, fast, local-first storage with full-text search.
-No external dependencies - just SQLite (built into Python).
-"""
-
-from __future__ import annotations
-
-import json
-import sqlite3
-import uuid
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Literal
-
-
-@dataclass
-class Memory:
-    """A single memory entry."""
-
-    content: str
-    category: Literal["preference", "fact", "context"] = "fact"
-    importance: float = 0.5
-    id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    created_at: datetime = field(default_factory=datetime.utcnow)
-    metadata: dict = field(default_factory=dict)
-
-
-@dataclass
-class PendingExtraction:
-    """A conversation pending memory extraction."""
-
-    user_id: str
-    query: str
-    response: str
-    id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    created_at: datetime = field(default_factory=datetime.utcnow)
-    status: Literal["pending", "processing", "done", "failed"] = "pending"
-
-
-class SQLiteMemoryStore:
-    """SQLite + FTS5 storage for memories.
-
-    Features:
-    - Full-text search via FTS5
-    - User isolation (each user_id has separate memories)
-    - Pending extractions for crash recovery
-    - Thread-safe with connection per call
-
-    Usage:
-        store = SQLiteMemoryStore("./memory.db")
-        store.save("alice", Memory(content="Prefers Python"))
-        results = store.search("alice", "python")
-    """
-
-    def __init__(self, db_path: str | Path = "headroom_memory.db"):
-        """Initialize the store.
-
-        Args:
-            db_path: Path to SQLite database file. Created if doesn't exist.
-        """
-        self.db_path = Path(db_path)
-        self._init_db()
-
-    def _get_conn(self) -> sqlite3.Connection:
-        """Get a new connection (thread-safe pattern)."""
-        conn = sqlite3.connect(str(self.db_path))
-        conn.row_factory = sqlite3.Row
-        return conn
-
-    def _init_db(self) -> None:
-        """Initialize database schema."""
-        with self._get_conn() as conn:
-            # Main memories table
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS memories (
-                    id TEXT PRIMARY KEY,
-                    user_id TEXT NOT NULL,
-                    content TEXT NOT NULL,
-                    category TEXT NOT NULL DEFAULT 'fact',
-                    importance REAL NOT NULL DEFAULT 0.5,
-                    created_at TEXT NOT NULL,
-                    metadata TEXT NOT NULL DEFAULT '{}'
-                )
-            """)
-
-            # FTS5 virtual table for full-text search
-            conn.execute("""
-                CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
-                    content,
-                    content='memories',
-                    content_rowid='rowid'
-                )
-            """)
-
-            # Triggers to keep FTS in sync
-            conn.execute("""
-                CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
-                    INSERT INTO memories_fts(rowid, content)
-                    VALUES (new.rowid, new.content);
-                END
-            """)
-
-            conn.execute("""
-                CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
-                    INSERT INTO memories_fts(memories_fts, rowid, content)
-                    VALUES ('delete', old.rowid, old.content);
-                END
-            """)
-
-            conn.execute("""
-                CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
-                    INSERT INTO memories_fts(memories_fts, rowid, content)
-                    VALUES ('delete', old.rowid, old.content);
-                    INSERT INTO memories_fts(rowid, content)
-                    VALUES (new.rowid, new.content);
-                END
-            """)
-
-            # Index for user_id filtering
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_memories_user_id
-                ON memories(user_id)
-            """)
-
-            # Pending extractions table (for crash recovery)
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS pending_extractions (
-                    id TEXT PRIMARY KEY,
-                    user_id TEXT NOT NULL,
-                    query TEXT NOT NULL,
-                    response TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    status TEXT NOT NULL DEFAULT 'pending'
-                )
-            """)
-
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_pending_status
-                ON pending_extractions(status)
-            """)
-
-            conn.commit()
-
-    def save(self, user_id: str, memory: Memory) -> None:
-        """Save a memory for a user.
-
-        Args:
-            user_id: User identifier for isolation
-            memory: Memory to save
-        """
-        with self._get_conn() as conn:
-            conn.execute(
-                """
-                INSERT INTO memories (id, user_id, content, category, importance, created_at, metadata)
-                VALUES (?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    memory.id,
-                    user_id,
-                    memory.content,
-                    memory.category,
-                    memory.importance,
-                    memory.created_at.isoformat(),
-                    json.dumps(memory.metadata),
-                ),
-            )
-            conn.commit()
-
-    def search(self, user_id: str, query: str, top_k: int = 5) -> list[Memory]:
-        """Search memories using FTS5 full-text search.
-
-        Args:
-            user_id: User identifier for isolation
-            query: Search query (auto-escaped, or use raw FTS5 syntax with prefix '_raw:')
-            top_k: Maximum number of results
-
-        Returns:
-            List of matching memories, ranked by relevance
-        """
-        # Sanitize query for FTS5 (escape special characters unless raw mode)
-        if query.startswith("_raw:"):
-            fts_query = query[5:]  # Use raw FTS5 syntax
-        else:
-            fts_query = self._sanitize_fts_query(query)
-
-        if not fts_query.strip():
-            return []
-
-        with self._get_conn() as conn:
-            # Use FTS5 MATCH with BM25 ranking, filtered by user_id
-            cursor = conn.execute(
-                """
-                SELECT m.*, bm25(memories_fts) as rank
-                FROM memories m
-                JOIN memories_fts ON m.rowid = memories_fts.rowid
-                WHERE memories_fts MATCH ? AND m.user_id = ?
-                ORDER BY rank
-                LIMIT ?
-                """,
-                (fts_query, user_id, top_k),
-            )
-
-            results = []
-            for row in cursor:
-                results.append(
-                    Memory(
-                        id=row["id"],
-                        content=row["content"],
-                        category=row["category"],
-                        importance=row["importance"],
-                        created_at=datetime.fromisoformat(row["created_at"]),
-                        metadata=json.loads(row["metadata"]),
-                    )
-                )
-            return results
-
-    def _sanitize_fts_query(self, query: str) -> str:
-        """Sanitize a query for FTS5.
-
-        Escapes special characters and converts to prefix search for better matching.
-
-        Args:
-            query: Raw user query
-
-        Returns:
-            FTS5-safe query string
-        """
-        # FTS5 special characters that need escaping
-        # We use a simple approach: extract words and use OR between them
-        import re
-
-        # Extract alphanumeric words
-        words = re.findall(r"\w+", query)
-
-        if not words:
-            return ""
-
-        # Use OR between words with prefix matching for flexibility
-        # This allows "What language" to match "Python" memories when searching
-        # by using prefix matching (word*)
-        escaped_words = []
-        for word in words:
-            # Quote each word to handle any remaining special chars
-            escaped_words.append(f'"{word}"')
-
-        return " OR ".join(escaped_words)
-
-    def get_all(self, user_id: str) -> list[Memory]:
-        """Get all memories for a user.
-
-        Args:
-            user_id: User identifier
-
-        Returns:
-            All memories for the user, ordered by creation time (newest first)
-        """
-        with self._get_conn() as conn:
-            cursor = conn.execute(
-                """
-                SELECT * FROM memories
-                WHERE user_id = ?
-                ORDER BY created_at DESC
-                """,
-                (user_id,),
-            )
-
-            return [
-                Memory(
-                    id=row["id"],
-                    content=row["content"],
-                    category=row["category"],
-                    importance=row["importance"],
-                    created_at=datetime.fromisoformat(row["created_at"]),
-                    metadata=json.loads(row["metadata"]),
-                )
-                for row in cursor
-            ]
-
-    def delete(self, user_id: str, memory_id: str) -> bool:
-        """Delete a specific memory.
-
-        Args:
-            user_id: User identifier
-            memory_id: ID of memory to delete
-
-        Returns:
-            True if deleted, False if not found
-        """
-        with self._get_conn() as conn:
-            cursor = conn.execute(
-                "DELETE FROM memories WHERE id = ? AND user_id = ?",
-                (memory_id, user_id),
-            )
-            conn.commit()
-            return cursor.rowcount > 0
-
-    def clear(self, user_id: str) -> int:
-        """Delete all memories for a user.
-
-        Args:
-            user_id: User identifier
-
-        Returns:
-            Number of memories deleted
-        """
-        with self._get_conn() as conn:
-            cursor = conn.execute(
-                "DELETE FROM memories WHERE user_id = ?",
-                (user_id,),
-            )
-            conn.commit()
-            return cursor.rowcount
-
-    def stats(self, user_id: str) -> dict:
-        """Get memory statistics for a user.
-
-        Args:
-            user_id: User identifier
-
-        Returns:
-            Dict with count, categories breakdown, etc.
-        """
-        with self._get_conn() as conn:
-            # Total count
-            total = conn.execute(
-                "SELECT COUNT(*) as count FROM memories WHERE user_id = ?",
-                (user_id,),
-            ).fetchone()["count"]
-
-            # Category breakdown
-            categories = {}
-            for row in conn.execute(
-                """
-                SELECT category, COUNT(*) as count
-                FROM memories WHERE user_id = ?
-                GROUP BY category
-                """,
-                (user_id,),
-            ):
-                categories[row["category"]] = row["count"]
-
-            return {
-                "total": total,
-                "categories": categories,
-            }
-
-    # --- Pending Extractions (for crash recovery) ---
-
-    def queue_extraction(self, pending: PendingExtraction) -> None:
-        """Queue a conversation for memory extraction.
-
-        Args:
-            pending: The pending extraction to queue
-        """
-        with self._get_conn() as conn:
-            conn.execute(
-                """
-                INSERT INTO pending_extractions (id, user_id, query, response, created_at, status)
-                VALUES (?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    pending.id,
-                    pending.user_id,
-                    pending.query,
-                    pending.response,
-                    pending.created_at.isoformat(),
-                    pending.status,
-                ),
-            )
-            conn.commit()
-
-    def get_pending_extractions(
-        self, limit: int = 10, status: str = "pending"
-    ) -> list[PendingExtraction]:
-        """Get pending extractions for processing.
-
-        Args:
-            limit: Maximum number to return
-            status: Filter by status
-
-        Returns:
-            List of pending extractions
-        """
-        with self._get_conn() as conn:
-            cursor = conn.execute(
-                """
-                SELECT * FROM pending_extractions
-                WHERE status = ?
-                ORDER BY created_at ASC
-                LIMIT ?
-                """,
-                (status, limit),
-            )
-
-            return [
-                PendingExtraction(
-                    id=row["id"],
-                    user_id=row["user_id"],
-                    query=row["query"],
-                    response=row["response"],
-                    created_at=datetime.fromisoformat(row["created_at"]),
-                    status=row["status"],
-                )
-                for row in cursor
-            ]
-
-    def update_extraction_status(self, extraction_id: str, status: str) -> None:
-        """Update the status of a pending extraction.
-
-        Args:
-            extraction_id: ID of the extraction
-            status: New status
-        """
-        with self._get_conn() as conn:
-            conn.execute(
-                "UPDATE pending_extractions SET status = ? WHERE id = ?",
-                (status, extraction_id),
-            )
-            conn.commit()
-
-    def delete_extraction(self, extraction_id: str) -> None:
-        """Delete a completed extraction.
-
-        Args:
-            extraction_id: ID of the extraction to delete
-        """
-        with self._get_conn() as conn:
-            conn.execute(
-                "DELETE FROM pending_extractions WHERE id = ?",
-                (extraction_id,),
-            )
-            conn.commit()

headroom/memory/worker.py

@@ -1,260 +0,0 @@
-"""Background worker for batched memory extraction.
-
-Collects conversations in a queue and processes them in batches,
-reducing LLM calls and improving efficiency.
-"""
-
-from __future__ import annotations
-
-import atexit
-import logging
-import threading
-import time
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from headroom.memory.extractor import MemoryExtractor
-    from headroom.memory.store import SQLiteMemoryStore
-
-
-logger = logging.getLogger(__name__)
-
-
-class ExtractionWorker:
-    """Background worker that batches memory extractions.
-
-    Features:
-    - Collects conversations in a queue
-    - Processes in batches (configurable size and timeout)
-    - Persists pending work to SQLite for crash recovery
-    - Thread-safe, daemon thread (stops with main program)
-
-    Usage:
-        worker = ExtractionWorker(store, extractor)
-        worker.start()
-        worker.schedule("alice", "I prefer Python", "Great choice!")
-        # ... later, memories are extracted and saved automatically
-    """
-
-    def __init__(
-        self,
-        store: SQLiteMemoryStore,
-        extractor: MemoryExtractor,
-        batch_size: int = 10,
-        max_wait_seconds: float = 30.0,
-    ):
-        """Initialize the worker.
-
-        Args:
-            store: Memory store for saving extracted memories
-            extractor: Extractor for processing conversations
-            batch_size: Max conversations per batch
-            max_wait_seconds: Max time to wait before processing partial batch
-        """
-        self.store = store
-        self.extractor = extractor
-        self.batch_size = batch_size
-        self.max_wait_seconds = max_wait_seconds
-
-        self._queue: list[tuple[str, str, str]] = []  # (user_id, query, response)
-        self._lock = threading.Lock()
-        self._event = threading.Event()
-        self._running = False
-        self._thread: threading.Thread | None = None
-
-        # Register cleanup on exit
-        atexit.register(self._cleanup)
-
-    def start(self) -> None:
-        """Start the background worker thread."""
-        if self._running:
-            return
-
-        self._running = True
-        self._thread = threading.Thread(target=self._run, daemon=True)
-        self._thread.start()
-
-        # Process any pending extractions from previous runs (crash recovery)
-        self._recover_pending()
-
-    def stop(self, wait: bool = True, timeout: float = 5.0) -> None:
-        """Stop the worker.
-
-        Args:
-            wait: If True, process remaining queue before stopping
-            timeout: Max time to wait for remaining work
-        """
-        if not self._running:
-            return
-
-        self._running = False
-        self._event.set()  # Wake up the thread
-
-        if wait and self._thread:
-            self._thread.join(timeout=timeout)
-
-    def schedule(self, user_id: str, query: str, response: str) -> None:
-        """Schedule a conversation for memory extraction.
-
-        Non-blocking - returns immediately and extracts in background.
-
-        Args:
-            user_id: User identifier
-            query: User's message
-            response: Assistant's response
-        """
-        # Persist to SQLite first (crash recovery)
-        from headroom.memory.store import PendingExtraction
-
-        pending = PendingExtraction(
-            user_id=user_id,
-            query=query,
-            response=response,
-        )
-        self.store.queue_extraction(pending)
-
-        # Add to in-memory queue
-        with self._lock:
-            self._queue.append((user_id, query, response))
-
-            # Wake up worker if batch is full
-            if len(self._queue) >= self.batch_size:
-                self._event.set()
-
-    def flush(self, timeout: float = 60.0) -> bool:
-        """Force immediate processing of all queued extractions.
-
-        Blocks until all pending extractions are processed or timeout.
-
-        Args:
-            timeout: Max time to wait in seconds
-
-        Returns:
-            True if all extractions completed, False if timed out
-        """
-        # Signal worker to process immediately by temporarily setting max_wait to 0
-        original_max_wait = self.max_wait_seconds
-        self.max_wait_seconds = 0
-        self._event.set()
-
-        # Wait for queue to empty
-        start = time.time()
-        while time.time() - start < timeout:
-            pending = self.store.get_pending_extractions(limit=1, status="pending")
-            if not pending:
-                self.max_wait_seconds = original_max_wait
-                return True
-            time.sleep(0.5)
-
-        self.max_wait_seconds = original_max_wait
-        return False
-
-    def _run(self) -> None:
-        """Main worker loop."""
-        last_process_time = time.time()
-
-        while self._running:
-            # Wait for batch to fill or timeout
-            self._event.wait(timeout=1.0)
-            self._event.clear()
-
-            now = time.time()
-            time_since_last = now - last_process_time
-
-            with self._lock:
-                should_process = len(self._queue) >= self.batch_size or (
-                    self._queue and time_since_last >= self.max_wait_seconds
-                )
-
-                if should_process:
-                    batch = self._queue[: self.batch_size]
-                    self._queue = self._queue[self.batch_size :]
-                else:
-                    batch = []
-
-            if batch:
-                self._process_batch(batch)
-                last_process_time = time.time()
-
-        # Process remaining queue on shutdown
-        with self._lock:
-            remaining = self._queue[:]
-            self._queue = []
-
-        if remaining:
-            self._process_batch(remaining)
-
-    def _process_batch(self, batch: list[tuple[str, str, str]]) -> None:
-        """Process a batch of conversations.
-
-        Args:
-            batch: List of (user_id, query, response) tuples
-        """
-        logger.debug(f"Processing batch of {len(batch)} conversations")
-
-        try:
-            # Extract memories
-            result = self.extractor.extract_batch(batch)
-
-            # Save memories
-            for user_id, memories in result.items():
-                for memory in memories:
-                    self.store.save(user_id, memory)
-                    logger.debug(f"Saved memory for {user_id}: {memory.content[:50]}...")
-
-            # Mark pending extractions as done
-            # Note: In a production system, we'd track exact IDs
-            # For simplicity, we clear pending by matching user/query/response
-            self._mark_batch_done(batch)
-
-        except Exception as e:
-            logger.error(f"Batch extraction failed: {e}")
-            self._mark_batch_failed(batch)
-
-    def _recover_pending(self) -> None:
-        """Recover pending extractions from previous runs."""
-        pending = self.store.get_pending_extractions(limit=100, status="pending")
-
-        if not pending:
-            return
-
-        logger.info(f"Recovering {len(pending)} pending extractions")
-
-        with self._lock:
-            for p in pending:
-                self._queue.append((p.user_id, p.query, p.response))
-
-        # Trigger processing
-        self._event.set()
-
-    def _mark_batch_done(self, batch: list[tuple[str, str, str]]) -> None:
-        """Mark batch items as completed in the pending table."""
-        # Get pending extractions and mark matching ones as done
-        pending = self.store.get_pending_extractions(limit=100)
-
-        for user_id, query, response in batch:
-            for p in pending:
-                if p.user_id == user_id and p.query == query and p.response == response:
-                    self.store.delete_extraction(p.id)
-                    break
-
-    def _mark_batch_failed(self, batch: list[tuple[str, str, str]]) -> None:
-        """Mark batch items as failed in the pending table."""
-        pending = self.store.get_pending_extractions(limit=100)
-
-        for user_id, query, response in batch:
-            for p in pending:
-                if p.user_id == user_id and p.query == query and p.response == response:
-                    self.store.update_extraction_status(p.id, "failed")
-                    break
-
-    def _cleanup(self) -> None:
-        """Cleanup on program exit."""
-        if self._running:
-            self.stop(wait=True, timeout=2.0)
-
-    @property
-    def queue_size(self) -> int:
-        """Get current queue size."""
-        with self._lock:
-            return len(self._queue)

headroom/memory/wrapper.py

@@ -1,32 +1,47 @@
 """Memory wrapper - the main API for Headroom Memory.
 
-One-line integration:
+One-line integration with zero-latency inline extraction:
     from headroom import with_memory
     client = with_memory(OpenAI(), user_id="alice")
+
+This uses the Letta/MemGPT approach - memories are extracted inline
+as part of the LLM response, not in a separate API call.
 """
 
 from __future__ import annotations
 
+import asyncio
 import copy
+import logging
 from pathlib import Path
 from typing import Any
 
-from headroom.memory.extractor import MemoryExtractor
-from headroom.memory.store import Memory, SQLiteMemoryStore
-from headroom.memory.worker import ExtractionWorker
+from headroom.memory.config import EmbedderBackend, MemoryConfig
+from headroom.memory.core import HierarchicalMemory
+from headroom.memory.inline_extractor import (
+    inject_memory_instruction,
+    parse_response_with_memory,
+)
+from headroom.memory.models import Memory, MemoryCategory
+
+logger = logging.getLogger(__name__)
 
 
 class MemoryWrapper:
-    """Wraps an LLM client to add automatic memory.
+    """Wraps an LLM client to add automatic memory with zero extra latency.
+
+    Uses inline extraction (Letta-style) - memories are extracted as part
+    of the LLM response, not in a separate API call.
 
     Intercepts chat completions to:
-    1. BEFORE: Inject relevant memories into user message
-    2. AFTER: Queue conversation for background memory extraction
+    1. BEFORE: Inject relevant memories into user message (semantic search)
+    2. DURING: Memory instruction in system prompt
+    3. AFTER: Parse response to extract and store memories
 
-    The system prompt is left unchanged to preserve prompt caching.
+    The original system prompt is preserved for caching.
 
     Usage:
-        client = MemoryWrapper(OpenAI(), user_id="alice")
+        client = with_memory(OpenAI(), user_id="alice")
         response = client.chat.completions.create(...)
     """
 
@@ -35,10 +50,12 @@ class MemoryWrapper:
         client: Any,
         user_id: str,
         db_path: str | Path = "headroom_memory.db",
-        extraction_model: str | None = None,
         top_k: int = 5,
-        _extractor: Any = None,  # For testing - inject mock
-        _store: SQLiteMemoryStore | None = None,  # For testing
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        embedder_backend: EmbedderBackend = EmbedderBackend.LOCAL,
+        openai_api_key: str | None = None,
+        _memory: HierarchicalMemory | None = None,  # For testing
     ):
         """Initialize the memory wrapper.
 
@@ -46,53 +63,61 @@ class MemoryWrapper:
             client: LLM client (OpenAI, Anthropic, etc.)
             user_id: User identifier for memory isolation
             db_path: Path to SQLite database
-            extraction_model: Override extraction model (auto-detect if None)
             top_k: Number of memories to inject
-            _extractor: Override extractor (for testing)
-            _store: Override store (for testing)
+            session_id: Optional session ID for session-scoped memories
+            agent_id: Optional agent ID for agent-scoped memories
+            embedder_backend: Which embedder to use (LOCAL or OPENAI)
+            openai_api_key: API key if using OpenAI embeddings
+            _memory: Override memory system (for testing)
         """
         self._client = client
         self._user_id = user_id
+        self._session_id = session_id
+        self._agent_id = agent_id
         self._top_k = top_k
-
-        # Initialize store
-        self._store = _store or SQLiteMemoryStore(db_path)
-
-        # Initialize extractor
-        self._extractor = _extractor or MemoryExtractor(client, model=extraction_model)
-
-        # Initialize background worker with shorter wait for responsiveness
-        self._worker = ExtractionWorker(
-            store=self._store,
-            extractor=self._extractor,
-            max_wait_seconds=5.0,  # Process partial batches after 5s
+        self._db_path = Path(db_path)
+
+        # Initialize memory system (async, so we defer)
+        self._memory = _memory
+        self._memory_config = MemoryConfig(
+            db_path=self._db_path,
+            embedder_backend=embedder_backend,
+            openai_api_key=openai_api_key,
         )
-        self._worker.start()
+        self._initialized = _memory is not None
 
         # Create wrapped chat interface
         self.chat = _WrappedChat(self)
 
-    def flush_extractions(self, timeout: float = 60.0) -> bool:
-        """Force immediate processing of all queued extractions.
-
-        Useful for testing or when you need to ensure memories are saved.
-
-        Args:
-            timeout: Max time to wait in seconds
-
-        Returns:
-            True if all extractions completed, False if timed out
-        """
-        return self._worker.flush(timeout=timeout)
+    def _ensure_initialized(self) -> None:
+        """Ensure memory system is initialized (sync wrapper for async init)."""
+        if not self._initialized:
+            # Run async initialization in sync context
+            loop = asyncio.new_event_loop()
+            try:
+                self._memory = loop.run_until_complete(
+                    HierarchicalMemory.create(self._memory_config)
+                )
+                self._initialized = True
+            finally:
+                loop.close()
 
     @property
     def memory(self) -> _MemoryAPI:
         """Direct access to memory operations."""
-        return _MemoryAPI(self._store, self._user_id)
+        self._ensure_initialized()
+        assert self._memory is not None
+        return _MemoryAPI(
+            self._memory,
+            self._user_id,
+            self._session_id,
+            self._agent_id,
+        )
 
     def _inject_memories(self, messages: list[dict]) -> list[dict]:
         """Inject relevant memories into messages.
 
+        Uses semantic search to find relevant memories.
         Memories are prepended to the FIRST user message to preserve
         system prompt caching.
 
@@ -102,7 +127,10 @@ class MemoryWrapper:
         Returns:
             New messages list with memories injected
         """
-        # Find the last user message
+        self._ensure_initialized()
+        assert self._memory is not None
+
+        # Find the last user message for search context
         user_content = None
         for msg in reversed(messages):
             if msg.get("role") == "user":
@@ -112,20 +140,27 @@ class MemoryWrapper:
         if not user_content:
             return messages
 
-        # Search for relevant memories
-        memories = self._store.search(
-            self._user_id,
-            str(user_content),
-            top_k=self._top_k,
-        )
+        # Search for relevant memories (async -> sync)
+        loop = asyncio.new_event_loop()
+        try:
+            memories = loop.run_until_complete(
+                self._memory.search(
+                    query=str(user_content),
+                    user_id=self._user_id,
+                    session_id=self._session_id,
+                    top_k=self._top_k,
+                )
+            )
+        finally:
+            loop.close()
 
         if not memories:
             return messages
 
-        # Build context block
+        # Build context block (search returns VectorSearchResult with .memory attr)
         context_lines = ["<context>"]
-        for mem in memories:
-            context_lines.append(f"- {mem.content}")
+        for result in memories:
+            context_lines.append(f"- {result.memory.content}")
         context_lines.append("</context>")
         context_block = "\n".join(context_lines)
 
@@ -139,14 +174,42 @@ class MemoryWrapper:
 
         return new_messages
 
-    def _queue_extraction(self, query: str, response: str) -> None:
-        """Queue conversation for background memory extraction.
+    def _store_memories(self, memories: list[dict[str, Any]]) -> None:
+        """Store extracted memories.
 
         Args:
-            query: User's message
-            response: Assistant's response
+            memories: List of memory dicts from inline extraction
         """
-        self._worker.schedule(self._user_id, query, response)
+        self._ensure_initialized()
+        assert self._memory is not None
+
+        loop = asyncio.new_event_loop()
+        try:
+            for mem in memories:
+                content = mem.get("content", "")
+                category_str = mem.get("category", "fact")
+
+                # Map string category to enum
+                category_map = {
+                    "preference": MemoryCategory.PREFERENCE,
+                    "fact": MemoryCategory.FACT,
+                    "context": MemoryCategory.CONTEXT,
+                }
+                category = category_map.get(category_str, MemoryCategory.FACT)
+
+                if content:
+                    loop.run_until_complete(
+                        self._memory.add(
+                            content=content,
+                            user_id=self._user_id,
+                            session_id=self._session_id,
+                            agent_id=self._agent_id,
+                            category=category,
+                            importance=0.7,  # Default importance for extracted memories
+                        )
+                    )
+        finally:
+            loop.close()
 
 
 class _WrappedChat:
@@ -158,66 +221,77 @@ class _WrappedChat:
 
 
 class _WrappedCompletions:
-    """Wrapped completions that add memory to requests."""
+    """Wrapped completions with inline memory extraction."""
 
     def __init__(self, wrapper: MemoryWrapper):
         self._wrapper = wrapper
 
     def create(self, **kwargs: Any) -> Any:
-        """Create a chat completion with memory injection.
+        """Create a chat completion with memory injection and inline extraction.
 
-        This intercepts the request to:
-        1. Inject relevant memories into user message
-        2. Forward to the real client
-        3. Queue response for background extraction
+        Flow:
+        1. Search for relevant memories (semantic)
+        2. Inject memories into user message
+        3. Add memory extraction instruction to system prompt
+        4. Forward to LLM
+        5. Parse response to extract memories
+        6. Store extracted memories
+        7. Return clean response (without memory block)
 
         All kwargs are passed through to the underlying client.
         """
         messages = kwargs.get("messages", [])
 
-        # 1. Inject memories into user message
+        # 1. Inject relevant memories into user message
         enhanced_messages = self._wrapper._inject_memories(messages)
+
+        # 2. Add memory extraction instruction to system prompt
+        enhanced_messages = inject_memory_instruction(enhanced_messages, short=True)
         kwargs["messages"] = enhanced_messages
 
-        # 2. Forward to real client
+        # 3. Forward to LLM
         response = self._wrapper._client.chat.completions.create(**kwargs)
 
-        # 3. Queue for extraction (non-blocking)
-        self._extract_and_queue(messages, response)
-
-        return response
-
-    def _extract_and_queue(self, original_messages: list[dict], response: Any) -> None:
-        """Extract query and response, queue for extraction."""
-        # Get the last user message (without context injection)
-        user_query = None
-        for msg in reversed(original_messages):
-            if msg.get("role") == "user":
-                user_query = msg.get("content", "")
-                break
+        # 4. Parse response and extract memories
+        raw_content = response.choices[0].message.content
+        parsed = parse_response_with_memory(raw_content)
 
-        if not user_query:
-            return
+        # 5. Store extracted memories
+        if parsed.memories:
+            self._wrapper._store_memories(parsed.memories)
+            logger.debug(f"Extracted and stored {len(parsed.memories)} memories")
 
-        # Get assistant response
-        try:
-            assistant_response = response.choices[0].message.content
-        except (AttributeError, IndexError):
-            return
+        # 6. Return clean response (modify in place)
+        response.choices[0].message.content = parsed.content
 
-        if assistant_response:
-            self._wrapper._queue_extraction(user_query, assistant_response)
+        return response
 
 
 class _MemoryAPI:
     """Direct API for memory operations."""
 
-    def __init__(self, store: SQLiteMemoryStore, user_id: str):
-        self._store = store
+    def __init__(
+        self,
+        memory: HierarchicalMemory,
+        user_id: str,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+    ):
+        self._memory = memory
         self._user_id = user_id
+        self._session_id = session_id
+        self._agent_id = agent_id
+
+    def _run_async(self, coro: Any) -> Any:
+        """Run async coroutine in sync context."""
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(coro)
+        finally:
+            loop.close()
 
     def search(self, query: str, top_k: int = 5) -> list[Memory]:
-        """Search memories.
+        """Semantic search for memories.
 
         Args:
             query: Search query
@@ -226,67 +300,113 @@ class _MemoryAPI:
         Returns:
             Matching memories
         """
-        return self._store.search(self._user_id, query, top_k)
+        results = self._run_async(
+            self._memory.search(
+                query=query,
+                user_id=self._user_id,
+                session_id=self._session_id,
+                top_k=top_k,
+            )
+        )
+        # Extract Memory objects from VectorSearchResult
+        return [r.memory for r in results]
 
     def add(
         self,
         content: str,
-        category: str = "fact",
+        category: str | MemoryCategory = "fact",
         importance: float = 0.5,
     ) -> Memory:
         """Manually add a memory.
 
         Args:
             content: Memory content
-            category: preference, fact, or context
+            category: preference, fact, or context (or MemoryCategory enum)
             importance: 0.0-1.0
 
         Returns:
             The created memory
         """
-        memory = Memory(
-            content=content,
-            category=category,  # type: ignore
-            importance=importance,
+        # Map string category to enum
+        cat_enum: MemoryCategory
+        if isinstance(category, str):
+            category_map: dict[str, MemoryCategory] = {
+                "preference": MemoryCategory.PREFERENCE,
+                "fact": MemoryCategory.FACT,
+                "context": MemoryCategory.CONTEXT,
+                "episodic": MemoryCategory.CONTEXT,
+                "entity": MemoryCategory.ENTITY,
+                "decision": MemoryCategory.DECISION,
+                "insight": MemoryCategory.INSIGHT,
+            }
+            cat_enum = category_map.get(category, MemoryCategory.FACT)
+        else:
+            cat_enum = category
+
+        result: Memory = self._run_async(
+            self._memory.add(
+                content=content,
+                user_id=self._user_id,
+                session_id=self._session_id,
+                agent_id=self._agent_id,
+                category=cat_enum,
+                importance=importance,
+            )
         )
-        self._store.save(self._user_id, memory)
-        return memory
+        return result
 
     def get_all(self) -> list[Memory]:
         """Get all memories for this user."""
-        return self._store.get_all(self._user_id)
+        from headroom.memory.ports import MemoryFilter
 
-    def delete(self, memory_id: str) -> bool:
-        """Delete a specific memory."""
-        return self._store.delete(self._user_id, memory_id)
+        filter = MemoryFilter(user_id=self._user_id)
+        memories: list[Memory] = self._run_async(self._memory.query(filter))
+        return memories
 
     def clear(self) -> int:
         """Clear all memories for this user."""
-        return self._store.clear(self._user_id)
+        count: int = self._run_async(self._memory.clear_scope(user_id=self._user_id))
+        return count
 
     def stats(self) -> dict:
         """Get memory statistics."""
-        return self._store.stats(self._user_id)
+        memories = self.get_all()
+        categories: dict[str, int] = {}
+        for mem in memories:
+            cat = mem.category.value if hasattr(mem.category, "value") else str(mem.category)
+            categories[cat] = categories.get(cat, 0) + 1
+
+        return {
+            "total": len(memories),
+            "categories": categories,
+        }
 
 
 def with_memory(
     client: Any,
     user_id: str,
     db_path: str | Path = "headroom_memory.db",
-    extraction_model: str | None = None,
     top_k: int = 5,
+    session_id: str | None = None,
+    agent_id: str | None = None,
+    embedder_backend: EmbedderBackend = EmbedderBackend.LOCAL,
+    openai_api_key: str | None = None,
     **kwargs: Any,
 ) -> MemoryWrapper:
-    """Wrap an LLM client to add automatic memory.
+    """Wrap an LLM client to add automatic memory with zero extra latency.
 
-    One-line integration for adding persistent memory to any LLM client.
+    Uses inline extraction (Letta-style) - memories are extracted as part
+    of the LLM response, not in a separate API call.
 
     Args:
         client: LLM client (OpenAI, Anthropic, Mistral, Groq, etc.)
         user_id: User identifier for memory isolation
         db_path: Path to SQLite database (default: headroom_memory.db)
-        extraction_model: Override extraction model (auto-detects by default)
         top_k: Number of memories to inject per request (default: 5)
+        session_id: Optional session ID for session-scoped memories
+        agent_id: Optional agent ID for agent-scoped memories
+        embedder_backend: Which embedder to use (LOCAL or OPENAI)
+        openai_api_key: API key if using OpenAI embeddings
         **kwargs: Additional arguments passed to MemoryWrapper
 
     Returns:
@@ -302,7 +422,7 @@ def with_memory(
             model="gpt-4o",
             messages=[{"role": "user", "content": "I prefer Python"}]
         )
-        # Memory automatically extracted in background
+        # Memory automatically extracted INLINE (zero extra latency!)
 
         # Later...
         response = client.chat.completions.create(
@@ -315,7 +435,10 @@ def with_memory(
         client=client,
         user_id=user_id,
         db_path=db_path,
-        extraction_model=extraction_model,
         top_k=top_k,
+        session_id=session_id,
+        agent_id=agent_id,
+        embedder_backend=embedder_backend,
+        openai_api_key=openai_api_key,
         **kwargs,
     )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "headroom-ai"
-version = "0.2.15"
+version = "0.3.0"
 description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"
 readme = "README.md"
 license = "Apache-2.0"

tests/conftest.py

@@ -1,5 +1,11 @@
 """Shared pytest fixtures for Headroom tests."""
 
+# CRITICAL: Must be set before ANY imports that could trigger sentence_transformers
+# The Rust tokenizers use parallelism that deadlocks with pytest-asyncio
+import os
+
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
 import json
 import tempfile
 from datetime import datetime

tests/test_memory/conftest.py

@@ -1,147 +1,8 @@
-"""Test fixtures for Headroom Memory.
-
-Philosophy: Mock at boundaries, not internals.
-- SQLite: REAL (local, fast, no side effects)
-- LLM clients: MOCKED (external dependency)
-"""
+"""Test fixtures for Headroom Memory."""
 
 from __future__ import annotations
 
-import tempfile
-from pathlib import Path
-from typing import Any
-
-import pytest
-
-
-@pytest.fixture
-def temp_db():
-    """Fresh SQLite DB for each test - REAL database, auto-cleanup."""
-    with tempfile.TemporaryDirectory() as tmpdir:
-        db_path = Path(tmpdir) / "test_memory.db"
-        yield db_path
-
-
-@pytest.fixture
-def memory_store(temp_db):
-    """Real SQLite memory store."""
-    from headroom.memory.store import SQLiteMemoryStore
-
-    return SQLiteMemoryStore(temp_db)
-
-
-@pytest.fixture
-def mock_extractor():
-    """Extractor with controllable responses - for testing worker/wrapper."""
-    from headroom.memory.store import Memory
-
-    class MockExtractor:
-        def __init__(self):
-            self.calls: list[tuple[str, str]] = []
-            self.batch_calls: list[list[tuple[str, str, str]]] = []
-            self._response: list[Memory] = []
-            self._batch_response: dict[str, list[Memory]] = {}
-
-        def set_response(self, memories: list[Memory]) -> None:
-            self._response = memories
-
-        def set_batch_response(self, response: dict[str, list[Memory]]) -> None:
-            self._batch_response = response
-
-        def extract(self, query: str, response: str) -> list[Memory]:
-            self.calls.append((query, response))
-            return self._response
-
-        def extract_batch(
-            self, conversations: list[tuple[str, str, str]]
-        ) -> dict[str, list[Memory]]:
-            self.batch_calls.append(conversations)
-            return self._batch_response
-
-    return MockExtractor()
-
-
-@pytest.fixture
-def mock_openai_client():
-    """Fake OpenAI client - for testing wrapper without API calls."""
-
-    class MockMessage:
-        def __init__(self, content: str):
-            self.content = content
-
-    class MockChoice:
-        def __init__(self, content: str):
-            self.message = MockMessage(content)
-
-    class MockResponse:
-        def __init__(self, content: str = "Hello!"):
-            self.choices = [MockChoice(content)]
-
-    class MockCompletions:
-        def __init__(self):
-            self.calls: list[dict[str, Any]] = []
-            self._response = MockResponse()
-
-        def set_response(self, content: str) -> None:
-            self._response = MockResponse(content)
-
-        def create(self, **kwargs: Any) -> MockResponse:
-            self.calls.append(kwargs)
-            return self._response
-
-    class MockChat:
-        def __init__(self):
-            self.completions = MockCompletions()
-
-    class MockClient:
-        """Mock OpenAI client."""
-
-        def __init__(self):
-            self.chat = MockChat()
-
-    return MockClient()
-
-
-@pytest.fixture
-def mock_anthropic_client():
-    """Fake Anthropic client - for testing wrapper without API calls."""
-
-    class MockTextBlock:
-        def __init__(self, text: str):
-            self.text = text
-
-    class MockResponse:
-        def __init__(self, content: str = "Hello!"):
-            self.content = [MockTextBlock(content)]
-
-    class MockMessages:
-        def __init__(self):
-            self.calls: list[dict[str, Any]] = []
-            self._response = MockResponse()
-
-        def set_response(self, content: str) -> None:
-            self._response = MockResponse(content)
-
-        def create(self, **kwargs: Any) -> MockResponse:
-            self.calls.append(kwargs)
-            return self._response
-
-    class MockClient:
-        """Mock Anthropic client."""
-
-        def __init__(self):
-            self.messages = MockMessages()
-
-    return MockClient()
-
-
-@pytest.fixture
-def sample_memories():
-    """Sample memories for testing."""
-    from headroom.memory.store import Memory
+# CRITICAL: Must be set before ANY imports that could trigger sentence_transformers
+import os
 
-    return [
-        Memory(content="User prefers Python", category="preference", importance=0.8),
-        Memory(content="User works at a startup", category="fact", importance=0.7),
-        Memory(content="User is building an AI agent", category="context", importance=0.6),
-    ]
+os.environ["TOKENIZERS_PARALLELISM"] = "false"

tests/test_memory/test_extractor.py

@@ -1,337 +0,0 @@
-"""Tests for memory extractor.
-
-Mocks LLM HTTP responses to test extraction logic without external calls.
-"""
-
-from __future__ import annotations
-
-from unittest.mock import MagicMock
-
-from headroom.memory.extractor import (
-    CHEAP_MODELS,
-    MemoryExtractor,
-    detect_provider,
-    get_cheap_model,
-)
-
-
-class TestProviderDetection:
-    """Test provider detection from client class."""
-
-    def test_detect_openai(self):
-        """Detect OpenAI from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "openai.resources.chat"
-
-        result = detect_provider(mock_client)
-
-        assert result == "openai"
-
-    def test_detect_anthropic(self):
-        """Detect Anthropic from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "anthropic.resources"
-
-        result = detect_provider(mock_client)
-
-        assert result == "anthropic"
-
-    def test_detect_groq(self):
-        """Detect Groq from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "groq.resources"
-
-        result = detect_provider(mock_client)
-
-        assert result == "groq"
-
-    def test_detect_together(self):
-        """Detect Together from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "together.client"
-
-        result = detect_provider(mock_client)
-
-        assert result == "together"
-
-    def test_detect_fireworks(self):
-        """Detect Fireworks from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "fireworks.client"
-
-        result = detect_provider(mock_client)
-
-        assert result == "fireworks"
-
-    def test_detect_mistralai(self):
-        """Detect Mistral from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "mistralai.client"
-
-        result = detect_provider(mock_client)
-
-        assert result == "mistralai"
-
-    def test_detect_cohere(self):
-        """Detect Cohere from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "cohere.client"
-
-        result = detect_provider(mock_client)
-
-        assert result == "cohere"
-
-    def test_detect_google(self):
-        """Detect Google from module path."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "google.generativeai"
-
-        result = detect_provider(mock_client)
-
-        assert result == "google"
-
-    def test_detect_unknown_returns_none(self):
-        """Unknown provider returns None."""
-        mock_client = MagicMock()
-        mock_client.__class__.__module__ = "some.unknown.provider"
-
-        result = detect_provider(mock_client)
-
-        assert result is None
-
-
-class TestCheapModelMapping:
-    """Test cheap model selection."""
-
-    def test_all_providers_have_models(self):
-        """All expected providers have cheap models defined."""
-        expected_providers = [
-            "openai",
-            "anthropic",
-            "mistralai",
-            "groq",
-            "together",
-            "fireworks",
-            "google",
-            "cohere",
-        ]
-
-        for provider in expected_providers:
-            assert provider in CHEAP_MODELS, f"Missing model for {provider}"
-            assert CHEAP_MODELS[provider], f"Empty model for {provider}"
-
-    def test_get_cheap_model_returns_correct_model(self):
-        """get_cheap_model returns correct model for provider."""
-        assert get_cheap_model("openai") == "gpt-4o-mini"
-        assert get_cheap_model("anthropic") == "claude-3-5-haiku-latest"
-        assert get_cheap_model("groq") == "llama-3.3-70b-versatile"
-
-    def test_get_cheap_model_unknown_returns_none(self):
-        """Unknown provider returns None."""
-        assert get_cheap_model("unknown") is None
-
-
-class TestMemoryExtractorInit:
-    """Test extractor initialization."""
-
-    def test_auto_detects_provider_and_model(self, mock_openai_client):
-        """Extractor auto-detects provider and selects cheap model."""
-        # Mock the module path
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        extractor = MemoryExtractor(mock_openai_client)
-
-        assert extractor.provider == "openai"
-        assert extractor.model == "gpt-4o-mini"
-
-    def test_explicit_model_overrides_auto(self, mock_openai_client):
-        """Explicit model parameter overrides auto-detection."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        extractor = MemoryExtractor(mock_openai_client, model="gpt-4-turbo")
-
-        assert extractor.model == "gpt-4-turbo"
-
-    def test_unknown_provider_warns(self, mock_openai_client, caplog):
-        """Unknown provider logs warning."""
-        mock_openai_client.__class__.__module__ = "unknown.provider"
-
-        with caplog.at_level("WARNING"):
-            extractor = MemoryExtractor(mock_openai_client)
-
-        assert extractor.model is None
-        assert "Could not detect cheap model" in caplog.text
-
-
-class TestMemoryExtraction:
-    """Test memory extraction from conversations."""
-
-    def test_extracts_preference(self, mock_openai_client):
-        """Extracts preference from conversation."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        # Mock the LLM response
-        mock_openai_client.chat.completions.set_response(
-            '{"memories": [{"content": "Prefers Python", "category": "preference", "importance": 0.8}], "should_remember": true}'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        memories = extractor.extract(
-            "I really prefer Python for data science",
-            "Great choice! Python is excellent for data science.",
-        )
-
-        assert len(memories) == 1
-        assert memories[0].content == "Prefers Python"
-        assert memories[0].category == "preference"
-        assert memories[0].importance == 0.8
-
-    def test_extracts_multiple_memories(self, mock_openai_client):
-        """Extracts multiple memories from one conversation."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response(
-            '{"memories": ['
-            '{"content": "Works at a startup", "category": "fact", "importance": 0.7},'
-            '{"content": "Building an AI agent", "category": "context", "importance": 0.6}'
-            '], "should_remember": true}'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        memories = extractor.extract(
-            "I work at a startup building an AI agent",
-            "That sounds exciting!",
-        )
-
-        assert len(memories) == 2
-        assert memories[0].content == "Works at a startup"
-        assert memories[1].content == "Building an AI agent"
-
-    def test_skips_trivial_conversation(self, mock_openai_client):
-        """Returns empty for trivial conversations."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response(
-            '{"memories": [], "should_remember": false}'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        memories = extractor.extract("Hello", "Hi there!")
-
-        assert len(memories) == 0
-
-    def test_handles_json_in_code_block(self, mock_openai_client):
-        """Parses JSON wrapped in markdown code block."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response(
-            '```json\n{"memories": [{"content": "Likes vim", "category": "preference"}], "should_remember": true}\n```'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        memories = extractor.extract("I use vim", "Nice!")
-
-        assert len(memories) == 1
-        assert memories[0].content == "Likes vim"
-
-    def test_handles_malformed_json(self, mock_openai_client, caplog):
-        """Gracefully handles malformed JSON."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response("not valid json")
-
-        with caplog.at_level("WARNING"):
-            extractor = MemoryExtractor(mock_openai_client)
-            memories = extractor.extract("test", "test")
-
-        assert len(memories) == 0
-        assert "Failed to parse" in caplog.text
-
-    def test_no_extraction_without_model(self, mock_openai_client, caplog):
-        """Skips extraction if no model configured."""
-        mock_openai_client.__class__.__module__ = "unknown.provider"
-
-        with caplog.at_level("WARNING"):
-            extractor = MemoryExtractor(mock_openai_client)
-            memories = extractor.extract("test", "test")
-
-        assert len(memories) == 0
-        assert "No extraction model" in caplog.text
-
-
-class TestBatchExtraction:
-    """Test batch extraction."""
-
-    def test_batch_extracts_for_multiple_users(self, mock_openai_client):
-        """Batch extraction returns memories per user."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response(
-            '{"alice": {"memories": [{"content": "Likes Python", "category": "preference"}], "should_remember": true},'
-            '"bob": {"memories": [{"content": "Likes Java", "category": "preference"}], "should_remember": true}}'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        result = extractor.extract_batch(
-            [
-                ("alice", "I like Python", "Great!"),
-                ("bob", "I like Java", "Nice!"),
-            ]
-        )
-
-        assert "alice" in result
-        assert "bob" in result
-        assert result["alice"][0].content == "Likes Python"
-        assert result["bob"][0].content == "Likes Java"
-
-    def test_batch_empty_input_returns_empty(self, mock_openai_client):
-        """Empty batch returns empty dict."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        extractor = MemoryExtractor(mock_openai_client)
-        result = extractor.extract_batch([])
-
-        assert result == {}
-
-    def test_batch_handles_partial_results(self, mock_openai_client):
-        """Batch handles some users with no memories."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        mock_openai_client.chat.completions.set_response(
-            '{"alice": {"memories": [{"content": "Fact", "category": "fact"}], "should_remember": true},'
-            '"bob": {"memories": [], "should_remember": false}}'
-        )
-
-        extractor = MemoryExtractor(mock_openai_client)
-        result = extractor.extract_batch(
-            [
-                ("alice", "Important info", "Noted!"),
-                ("bob", "Hello", "Hi!"),
-            ]
-        )
-
-        assert "alice" in result
-        assert "bob" not in result  # No memories to remember
-
-
-class TestAnthropicProvider:
-    """Test Anthropic-specific API handling."""
-
-    def test_anthropic_uses_messages_api(self, mock_anthropic_client):
-        """Anthropic uses messages.create API."""
-        mock_anthropic_client.__class__.__module__ = "anthropic.resources"
-
-        mock_anthropic_client.messages.set_response(
-            '{"memories": [{"content": "Test", "category": "fact"}], "should_remember": true}'
-        )
-
-        extractor = MemoryExtractor(mock_anthropic_client)
-        memories = extractor.extract("test query", "test response")
-
-        assert len(memories) == 1
-        assert memories[0].content == "Test"
-
-        # Verify Anthropic API was called
-        assert len(mock_anthropic_client.messages.calls) == 1
-        call = mock_anthropic_client.messages.calls[0]
-        assert call["model"] == "claude-3-5-haiku-latest"

tests/test_memory/test_hierarchical.py

@@ -0,0 +1,804 @@
+"""Tests for the hierarchical memory system.
+
+Tests cover:
+- Memory models (Memory, ScopeLevel, MemoryCategory)
+- SQLite memory store
+- HNSW vector index
+- FTS5 text index
+- LRU cache
+- HierarchicalMemory orchestrator
+- Memory bubbling
+- Temporal versioning (supersession)
+"""
+
+# CRITICAL: Must set TOKENIZERS_PARALLELISM before any imports that might
+# trigger sentence_transformers/transformers loading. The Rust tokenizers
+# use parallelism that conflicts with Python's forking model, causing
+# deadlocks when combined with asyncio/pytest.
+# See: https://github.com/huggingface/transformers/issues/5486
+import os
+
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+import asyncio
+import tempfile
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from headroom.memory.adapters.cache import LRUMemoryCache
+from headroom.memory.adapters.fts5 import FTS5TextIndex
+from headroom.memory.adapters.sqlite import SQLiteMemoryStore
+from headroom.memory.models import Memory, MemoryCategory, ScopeLevel
+from headroom.memory.ports import MemoryFilter, TextFilter, VectorFilter
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def temp_db_path():
+    """Create a temporary database path."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        yield Path(f.name)
+
+
+@pytest.fixture
+def sample_memory():
+    """Create a sample memory for testing."""
+    return Memory(
+        content="User prefers Python over JavaScript",
+        user_id="alice",
+        session_id="session-123",
+        category=MemoryCategory.PREFERENCE,
+        importance=0.8,
+        entity_refs=["Python", "JavaScript"],
+        metadata={"source": "conversation"},
+    )
+
+
+@pytest.fixture
+def sample_embedding():
+    """Create a sample embedding vector."""
+    return np.random.randn(384).astype(np.float32)
+
+
+# =============================================================================
+# Memory Model Tests
+# =============================================================================
+
+
+class TestMemoryModel:
+    """Tests for the Memory dataclass."""
+
+    def test_memory_creation(self):
+        """Test basic memory creation."""
+        memory = Memory(
+            content="Test content",
+            user_id="test-user",
+        )
+        assert memory.content == "Test content"
+        assert memory.user_id == "test-user"
+        assert memory.id is not None  # Auto-generated UUID
+        assert memory.category == MemoryCategory.FACT  # Default
+        assert memory.importance == 0.5  # Default
+
+    def test_scope_level_computation(self):
+        """Test scope level is correctly computed from hierarchy fields."""
+        # USER level - only user_id
+        user_mem = Memory(content="test", user_id="alice")
+        assert user_mem.scope_level == ScopeLevel.USER
+
+        # SESSION level - user_id + session_id
+        session_mem = Memory(content="test", user_id="alice", session_id="sess-1")
+        assert session_mem.scope_level == ScopeLevel.SESSION
+
+        # AGENT level - user_id + session_id + agent_id
+        agent_mem = Memory(content="test", user_id="alice", session_id="sess-1", agent_id="agent-1")
+        assert agent_mem.scope_level == ScopeLevel.AGENT
+
+        # TURN level - all four
+        turn_mem = Memory(
+            content="test",
+            user_id="alice",
+            session_id="sess-1",
+            agent_id="agent-1",
+            turn_id="turn-1",
+        )
+        assert turn_mem.scope_level == ScopeLevel.TURN
+
+    def test_is_current_property(self):
+        """Test is_current property for supersession detection."""
+        current = Memory(content="test", user_id="alice")
+        assert current.is_current is True
+
+        superseded = Memory(content="test", user_id="alice", valid_until=datetime.utcnow())
+        assert superseded.is_current is False
+
+    def test_memory_serialization(self, sample_embedding):
+        """Test Memory to_dict and from_dict."""
+        memory = Memory(
+            content="Test content",
+            user_id="alice",
+            session_id="sess-1",
+            category=MemoryCategory.PREFERENCE,
+            importance=0.9,
+            entity_refs=["entity1"],
+            metadata={"key": "value"},
+            embedding=sample_embedding,
+        )
+
+        # Serialize
+        data = memory.to_dict()
+        assert data["content"] == "Test content"
+        assert data["user_id"] == "alice"
+        assert data["category"] == "preference"
+        assert data["embedding"] is not None
+
+        # Deserialize
+        restored = Memory.from_dict(data)
+        assert restored.content == memory.content
+        assert restored.user_id == memory.user_id
+        assert restored.category == memory.category
+        assert restored.importance == memory.importance
+        assert np.allclose(restored.embedding, memory.embedding)
+
+
+# =============================================================================
+# SQLite Store Tests
+# =============================================================================
+
+
+class TestSQLiteMemoryStore:
+    """Tests for SQLiteMemoryStore."""
+
+    @pytest.fixture
+    def store(self, temp_db_path):
+        """Create a SQLite store for testing."""
+        return SQLiteMemoryStore(temp_db_path)
+
+    @pytest.mark.asyncio
+    async def test_save_and_get(self, store, sample_memory):
+        """Test saving and retrieving a memory."""
+        await store.save(sample_memory)
+
+        retrieved = await store.get(sample_memory.id)
+        assert retrieved is not None
+        assert retrieved.id == sample_memory.id
+        assert retrieved.content == sample_memory.content
+        assert retrieved.user_id == sample_memory.user_id
+        assert retrieved.category == sample_memory.category
+
+    @pytest.mark.asyncio
+    async def test_save_batch(self, store):
+        """Test batch saving memories."""
+        memories = [Memory(content=f"Memory {i}", user_id="alice") for i in range(10)]
+
+        await store.save_batch(memories)
+
+        for memory in memories:
+            retrieved = await store.get(memory.id)
+            assert retrieved is not None
+            assert retrieved.content == memory.content
+
+    @pytest.mark.asyncio
+    async def test_delete(self, store, sample_memory):
+        """Test deleting a memory."""
+        await store.save(sample_memory)
+
+        deleted = await store.delete(sample_memory.id)
+        assert deleted is True
+
+        retrieved = await store.get(sample_memory.id)
+        assert retrieved is None
+
+    @pytest.mark.asyncio
+    async def test_query_by_user(self, store):
+        """Test querying memories by user_id."""
+        # Create memories for different users
+        alice_memories = [Memory(content=f"Alice {i}", user_id="alice") for i in range(5)]
+        bob_memories = [Memory(content=f"Bob {i}", user_id="bob") for i in range(3)]
+
+        await store.save_batch(alice_memories + bob_memories)
+
+        # Query Alice's memories
+        results = await store.query(MemoryFilter(user_id="alice"))
+        assert len(results) == 5
+
+        # Query Bob's memories
+        results = await store.query(MemoryFilter(user_id="bob"))
+        assert len(results) == 3
+
+    @pytest.mark.asyncio
+    async def test_query_by_category(self, store):
+        """Test querying memories by category."""
+        memories = [
+            Memory(content="Pref 1", user_id="alice", category=MemoryCategory.PREFERENCE),
+            Memory(content="Pref 2", user_id="alice", category=MemoryCategory.PREFERENCE),
+            Memory(content="Fact 1", user_id="alice", category=MemoryCategory.FACT),
+        ]
+
+        await store.save_batch(memories)
+
+        # Query preferences
+        results = await store.query(
+            MemoryFilter(user_id="alice", categories=[MemoryCategory.PREFERENCE])
+        )
+        assert len(results) == 2
+
+    @pytest.mark.asyncio
+    async def test_query_by_importance(self, store):
+        """Test querying memories by importance range."""
+        memories = [
+            Memory(content="Low", user_id="alice", importance=0.3),
+            Memory(content="Medium", user_id="alice", importance=0.5),
+            Memory(content="High", user_id="alice", importance=0.9),
+        ]
+
+        await store.save_batch(memories)
+
+        # Query high importance only
+        results = await store.query(MemoryFilter(user_id="alice", min_importance=0.8))
+        assert len(results) == 1
+        assert results[0].content == "High"
+
+    @pytest.mark.asyncio
+    async def test_query_by_scope_level(self, store):
+        """Test querying by explicit scope level."""
+        memories = [
+            Memory(content="User level", user_id="alice"),
+            Memory(content="Session level", user_id="alice", session_id="sess-1"),
+            Memory(content="Agent level", user_id="alice", session_id="sess-1", agent_id="agent-1"),
+        ]
+
+        await store.save_batch(memories)
+
+        # Query only USER level
+        results = await store.query(MemoryFilter(user_id="alice", scope_levels=[ScopeLevel.USER]))
+        assert len(results) == 1
+        assert results[0].content == "User level"
+
+        # Query SESSION level
+        results = await store.query(
+            MemoryFilter(user_id="alice", scope_levels=[ScopeLevel.SESSION])
+        )
+        assert len(results) == 1
+        assert results[0].content == "Session level"
+
+    @pytest.mark.asyncio
+    async def test_supersession(self, store):
+        """Test memory supersession."""
+        original = Memory(
+            content="User prefers Python",
+            user_id="alice",
+            category=MemoryCategory.PREFERENCE,
+        )
+        await store.save(original)
+
+        # Supersede with new preference
+        new_memory = Memory(
+            content="User now prefers Rust",
+            user_id="alice",
+            category=MemoryCategory.PREFERENCE,
+        )
+
+        superseded = await store.supersede(original.id, new_memory)
+
+        # New memory should be linked to old
+        assert superseded.supersedes == original.id
+
+        # Old memory should be marked as superseded
+        old_retrieved = await store.get(original.id)
+        assert old_retrieved.superseded_by == superseded.id
+        assert old_retrieved.valid_until is not None
+        assert old_retrieved.is_current is False
+
+        # New memory should be current
+        assert superseded.is_current is True
+
+    @pytest.mark.asyncio
+    async def test_get_history(self, store):
+        """Test getting supersession chain history."""
+        # Create a chain: v1 -> v2 -> v3
+        v1 = Memory(content="Version 1", user_id="alice")
+        await store.save(v1)
+
+        v2 = Memory(content="Version 2", user_id="alice")
+        v2 = await store.supersede(v1.id, v2)
+
+        v3 = Memory(content="Version 3", user_id="alice")
+        v3 = await store.supersede(v2.id, v3)
+
+        # Get history from middle
+        history = await store.get_history(v2.id, include_future=True)
+        assert len(history) == 3
+        assert history[0].content == "Version 1"
+        assert history[1].content == "Version 2"
+        assert history[2].content == "Version 3"
+
+    @pytest.mark.asyncio
+    async def test_clear_scope(self, store):
+        """Test clearing memories at a scope level."""
+        # Create memories at different scopes
+        memories = [
+            Memory(content="User 1", user_id="alice"),
+            Memory(content="User 2", user_id="alice"),
+            Memory(content="Session 1", user_id="alice", session_id="sess-1"),
+            Memory(content="Other user", user_id="bob"),
+        ]
+        await store.save_batch(memories)
+
+        # Clear Alice's session
+        deleted = await store.clear_scope("alice", session_id="sess-1")
+        assert deleted == 1
+
+        # Alice's user-level memories should remain
+        remaining = await store.query(MemoryFilter(user_id="alice"))
+        assert len(remaining) == 2
+
+
+# =============================================================================
+# LRU Cache Tests
+# =============================================================================
+
+
+class TestLRUMemoryCache:
+    """Tests for LRUMemoryCache."""
+
+    @pytest.fixture
+    def cache(self):
+        """Create a cache for testing."""
+        return LRUMemoryCache(max_size=5)
+
+    async def test_set_and_get(self, cache, sample_memory):
+        """Test basic cache put and get."""
+        await cache.put(sample_memory)
+
+        retrieved = await cache.get(sample_memory.id)
+        assert retrieved is not None
+        assert retrieved.id == sample_memory.id
+
+    async def test_lru_eviction(self, cache):
+        """Test LRU eviction when cache is full."""
+        # Fill cache with 5 memories
+        memories = [Memory(content=f"Mem {i}", user_id="alice") for i in range(5)]
+        for m in memories:
+            await cache.put(m)
+
+        assert cache.size == 5
+
+        # Add one more - should evict the first
+        new_mem = Memory(content="New", user_id="alice")
+        await cache.put(new_mem)
+
+        assert cache.size == 5
+        assert await cache.get(memories[0].id) is None  # First was evicted
+        assert await cache.get(new_mem.id) is not None
+
+    async def test_access_updates_lru_order(self, cache):
+        """Test that accessing a key moves it to end of LRU."""
+        memories = [Memory(content=f"Mem {i}", user_id="alice") for i in range(5)]
+        for m in memories:
+            await cache.put(m)
+
+        # Access the first memory (makes it most recently used)
+        await cache.get(memories[0].id)
+
+        # Add new memory - should evict second (now oldest)
+        new_mem = Memory(content="New", user_id="alice")
+        await cache.put(new_mem)
+
+        assert await cache.get(memories[0].id) is not None  # Still present
+        assert await cache.get(memories[1].id) is None  # Evicted
+
+    async def test_delete(self, cache, sample_memory):
+        """Test deleting from cache."""
+        await cache.put(sample_memory)
+        assert cache.size == 1
+
+        deleted = await cache.invalidate(sample_memory.id)
+        assert deleted is True
+        assert cache.size == 0
+        assert await cache.get(sample_memory.id) is None
+
+    async def test_clear(self, cache):
+        """Test clearing the cache."""
+        memories = [Memory(content=f"Mem {i}", user_id="alice") for i in range(3)]
+        for m in memories:
+            await cache.put(m)
+
+        await cache.clear()
+        assert cache.size == 0
+
+
+# =============================================================================
+# FTS5 Text Index Tests
+# =============================================================================
+
+
+class TestFTS5TextIndex:
+    """Tests for FTS5TextIndex."""
+
+    @pytest.fixture
+    def text_index(self, temp_db_path):
+        """Create a FTS5 text index for testing."""
+        return FTS5TextIndex(temp_db_path)
+
+    def test_index_and_search(self, text_index):
+        """Test indexing and searching text."""
+        # Index some memories
+        text_index.index("mem-1", "User prefers Python programming", {"user_id": "alice"})
+        text_index.index("mem-2", "JavaScript is also popular", {"user_id": "alice"})
+        text_index.index("mem-3", "Python is great for data science", {"user_id": "alice"})
+
+        # Search for Python
+        results = text_index.search("Python", k=10)
+        assert len(results) == 2
+
+        # Results should include memory IDs
+        result_ids = [r.memory_id for r in results]
+        assert "mem-1" in result_ids
+        assert "mem-3" in result_ids
+
+    def test_search_with_user_filter(self, text_index):
+        """Test searching with user filter."""
+        text_index.index("mem-1", "Python programming", {"user_id": "alice"})
+        text_index.index("mem-2", "Python scripting", {"user_id": "bob"})
+
+        # Search only Alice's memories
+        filter = TextFilter(user_id="alice")
+        results = text_index.search("Python", k=10, filter=filter)
+
+        assert len(results) == 1
+        assert results[0].memory_id == "mem-1"
+
+    def test_search_with_category_filter(self, text_index):
+        """Test searching with category filter."""
+        text_index.index("mem-1", "Prefers Python", {"user_id": "alice", "category": "preference"})
+        text_index.index("mem-2", "Python is installed", {"user_id": "alice", "category": "fact"})
+
+        # Search only preferences
+        filter = TextFilter(categories=[MemoryCategory.PREFERENCE])
+        results = text_index.search("Python", k=10, filter=filter)
+
+        assert len(results) == 1
+        assert results[0].memory_id == "mem-1"
+
+    def test_delete(self, text_index):
+        """Test deleting from text index."""
+        text_index.index("mem-1", "Test content", {"user_id": "alice"})
+
+        deleted = text_index.delete("mem-1")
+        assert deleted is True
+
+        results = text_index.search("Test", k=10)
+        assert len(results) == 0
+
+    def test_batch_index(self, text_index):
+        """Test batch indexing."""
+        memory_ids = ["mem-1", "mem-2", "mem-3"]
+        texts = ["Python code", "JavaScript code", "Rust code"]
+        metadata = [{"user_id": "alice"} for _ in range(3)]
+
+        text_index.index_batch(memory_ids, texts, metadata)
+
+        assert text_index.count() == 3
+
+
+# =============================================================================
+# Memory Config Tests
+# =============================================================================
+
+
+class TestMemoryConfig:
+    """Tests for MemoryConfig validation."""
+
+    def test_default_config(self):
+        """Test default configuration."""
+        from headroom.memory.config import MemoryConfig
+
+        config = MemoryConfig()
+        assert config.vector_dimension == 384
+        assert config.cache_enabled is True
+        assert config.auto_bubble is True
+
+    def test_invalid_dimension(self):
+        """Test that invalid dimension raises error."""
+        from headroom.memory.config import MemoryConfig
+
+        with pytest.raises(ValueError):
+            MemoryConfig(vector_dimension=0)
+
+    def test_openai_requires_api_key(self):
+        """Test that OpenAI backend requires API key."""
+        from headroom.memory.config import EmbedderBackend, MemoryConfig
+
+        with pytest.raises(ValueError, match="openai_api_key"):
+            MemoryConfig(embedder_backend=EmbedderBackend.OPENAI)
+
+
+# =============================================================================
+# Integration Tests
+# =============================================================================
+
+
+class TestIntegration:
+    """Integration tests that test multiple components together."""
+
+    @pytest.mark.asyncio
+    async def test_store_with_embeddings(self, temp_db_path, sample_embedding):
+        """Test storing and retrieving memories with embeddings."""
+        store = SQLiteMemoryStore(temp_db_path)
+
+        memory = Memory(
+            content="Test content",
+            user_id="alice",
+            embedding=sample_embedding,
+        )
+
+        await store.save(memory)
+
+        retrieved = await store.get(memory.id)
+        assert retrieved.embedding is not None
+        assert np.allclose(retrieved.embedding, sample_embedding)
+
+    @pytest.mark.asyncio
+    async def test_temporal_query(self, temp_db_path):
+        """Test point-in-time temporal queries."""
+        store = SQLiteMemoryStore(temp_db_path)
+
+        # Create a supersession chain
+        original = Memory(content="Original preference", user_id="alice")
+        await store.save(original)
+
+        # Capture time after original was created (valid_from is set at Memory creation)
+        time_when_original_valid = original.valid_from + timedelta(milliseconds=1)
+
+        # Wait a bit for time difference
+        await asyncio.sleep(0.01)
+
+        # Supersede
+        new_memory = Memory(content="New preference", user_id="alice")
+        supersede_time = datetime.utcnow()
+        await store.supersede(original.id, new_memory, supersede_time)
+
+        # Query at a point when original was valid (after its valid_from, before supersession)
+        # The past_time must be >= original.valid_from and < supersede_time
+        results = await store.query(
+            MemoryFilter(
+                user_id="alice", valid_at=time_when_original_valid, include_superseded=True
+            )
+        )
+        assert len(results) == 1
+        assert results[0].content == "Original preference"
+
+        # Query current - should return new
+        results = await store.query(MemoryFilter(user_id="alice"))
+        assert len(results) == 1
+        assert results[0].content == "New preference"
+
+    @pytest.mark.asyncio
+    async def test_hierarchical_scope_query(self, temp_db_path):
+        """Test hierarchical scope filtering."""
+        store = SQLiteMemoryStore(temp_db_path)
+
+        # Create memories at different scopes
+        user_mem = Memory(content="User pref", user_id="alice")
+        session_mem = Memory(content="Session context", user_id="alice", session_id="sess-1")
+        agent_mem = Memory(
+            content="Agent decision",
+            user_id="alice",
+            session_id="sess-1",
+            agent_id="agent-1",
+        )
+
+        await store.save_batch([user_mem, session_mem, agent_mem])
+
+        # Query user scope only - should get just user_mem
+        user_only = await store.query(MemoryFilter(user_id="alice", scope_levels=[ScopeLevel.USER]))
+        assert len(user_only) == 1
+        assert user_only[0].content == "User pref"
+
+        # Query all scopes for this user
+        all_memories = await store.query(MemoryFilter(user_id="alice"))
+        assert len(all_memories) == 3
+
+        # Query specific session
+        session_memories = await store.query(MemoryFilter(user_id="alice", session_id="sess-1"))
+        assert len(session_memories) == 2  # session and agent level
+
+
+# =============================================================================
+# HNSW Vector Index Tests
+# =============================================================================
+
+
+class TestHNSWVectorIndex:
+    """Tests for HNSWVectorIndex."""
+
+    @pytest.fixture
+    def vector_index(self, temp_db_path):
+        """Create an HNSW vector index for testing."""
+        from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+        return HNSWVectorIndex(dimension=384, save_path=temp_db_path.with_suffix(".hnsw"))
+
+    @pytest.mark.asyncio
+    async def test_index_and_search(self, vector_index):
+        """Test indexing and searching vectors."""
+
+        # Create memories with random embeddings
+        np.random.seed(42)
+        memories = []
+        for i in range(10):
+            embedding = np.random.randn(384).astype(np.float32)
+            memory = Memory(
+                content=f"Test content {i}",
+                user_id="alice",
+                embedding=embedding,
+            )
+            memories.append(memory)
+
+        # Index all memories
+        for memory in memories:
+            await vector_index.index(memory)
+
+        # Search with first memory's embedding - should find itself as most similar
+        filter = VectorFilter(
+            query_vector=memories[0].embedding,
+            top_k=3,
+            user_id="alice",
+        )
+        results = await vector_index.search(filter)
+        assert len(results) == 3
+        assert results[0].memory.id == memories[0].id
+        assert results[0].similarity > 0.99  # Should be very close to 1.0
+
+    @pytest.mark.asyncio
+    async def test_batch_index(self, vector_index):
+        """Test batch indexing."""
+
+        np.random.seed(42)
+        memories = []
+        for i in range(100):
+            embedding = np.random.randn(384).astype(np.float32)
+            memory = Memory(
+                content=f"Test content {i}",
+                user_id="alice",
+                embedding=embedding,
+            )
+            memories.append(memory)
+
+        count = await vector_index.index_batch(memories)
+
+        # Verify count
+        assert count == 100
+        assert vector_index.size == 100
+
+        # Search should work
+        filter = VectorFilter(
+            query_vector=memories[50].embedding,
+            top_k=5,
+            user_id="alice",
+        )
+        results = await vector_index.search(filter)
+        assert len(results) == 5
+        assert results[0].memory.id == memories[50].id
+
+    @pytest.mark.asyncio
+    async def test_remove(self, vector_index):
+        """Test removing from index."""
+        np.random.seed(42)
+        embedding = np.random.randn(384).astype(np.float32)
+        memory = Memory(
+            content="Test content",
+            user_id="alice",
+            embedding=embedding,
+        )
+        await vector_index.index(memory)
+
+        # HNSW doesn't support true deletion, but marks as deleted
+        removed = await vector_index.remove(memory.id)
+        assert removed is True
+
+    @pytest.mark.asyncio
+    async def test_persistence(self, temp_db_path):
+        """Test that index persists to disk."""
+        from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+        save_path = temp_db_path.with_suffix(".hnsw")
+        np.random.seed(42)
+        embedding = np.random.randn(384).astype(np.float32)
+        memory = Memory(
+            content="Test content",
+            user_id="alice",
+            embedding=embedding,
+        )
+
+        # Create and populate index
+        index1 = HNSWVectorIndex(dimension=384, save_path=save_path)
+        await index1.index(memory)
+        index1.save_index(save_path)
+
+        # Create new index and load from same path
+        index2 = HNSWVectorIndex(dimension=384, save_path=save_path)
+        index2.load_index(save_path)
+        assert index2.size == 1
+
+        filter = VectorFilter(
+            query_vector=embedding,
+            top_k=1,
+            user_id="alice",
+        )
+        results = await index2.search(filter)
+        assert results[0].memory.id == memory.id
+
+
+# =============================================================================
+# LocalEmbedder Tests
+# =============================================================================
+
+
+class TestLocalEmbedder:
+    """Tests for LocalEmbedder (sentence-transformers)."""
+
+    @pytest.fixture
+    def embedder(self):
+        """Create a local embedder for testing."""
+        from headroom.memory.adapters.embedders import LocalEmbedder
+
+        return LocalEmbedder()
+
+    @pytest.mark.asyncio
+    async def test_embed_single(self, embedder):
+        """Test embedding a single text."""
+        text = "User prefers Python programming"
+        embedding = await embedder.embed(text)
+
+        assert embedding is not None
+        assert embedding.shape == (384,)
+        assert embedding.dtype == np.float32
+
+    @pytest.mark.asyncio
+    async def test_embed_batch(self, embedder):
+        """Test embedding multiple texts."""
+        texts = [
+            "Python programming",
+            "JavaScript development",
+            "Rust systems programming",
+        ]
+        embeddings = await embedder.embed_batch(texts)
+
+        assert len(embeddings) == 3
+        for emb in embeddings:
+            assert emb.shape == (384,)
+
+    @pytest.mark.asyncio
+    async def test_similar_texts_have_high_similarity(self, embedder):
+        """Test that semantically similar texts have similar embeddings."""
+        text1 = "The user prefers Python for data analysis"
+        text2 = "Python is the user's preferred language for data science"
+        text3 = "The weather is sunny today"
+
+        emb1 = await embedder.embed(text1)
+        emb2 = await embedder.embed(text2)
+        emb3 = await embedder.embed(text3)
+
+        # Cosine similarity
+        def cosine_sim(a, b):
+            return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
+
+        # Similar texts should have high similarity
+        sim_related = cosine_sim(emb1, emb2)
+        sim_unrelated = cosine_sim(emb1, emb3)
+
+        assert sim_related > 0.7  # Related texts
+        assert sim_unrelated < 0.5  # Unrelated texts
+        assert sim_related > sim_unrelated
+
+    def test_dimension_property(self, embedder):
+        """Test that dimension property returns correct value."""
+        assert embedder.dimension == 384

tests/test_memory/test_inline_extractor.py

@@ -1,196 +0,0 @@
-"""Tests for inline memory extraction (Letta-style)."""
-
-from __future__ import annotations
-
-from headroom.memory.inline_extractor import (
-    MEMORY_INSTRUCTION,
-    MEMORY_INSTRUCTION_SHORT,
-    ParsedResponse,
-    inject_memory_instruction,
-    parse_response_with_memory,
-)
-
-
-class TestParseResponseWithMemory:
-    """Test response parsing to extract memories."""
-
-    def test_extracts_single_memory(self):
-        """Parse response with one memory."""
-        response = """Great choice! Python is excellent for backend development.
-
-<memory>{"memories": [{"content": "User prefers Python", "category": "preference"}]}</memory>"""
-
-        parsed = parse_response_with_memory(response)
-
-        assert (
-            parsed.content.strip() == "Great choice! Python is excellent for backend development."
-        )
-        assert len(parsed.memories) == 1
-        assert parsed.memories[0]["content"] == "User prefers Python"
-        assert parsed.memories[0]["category"] == "preference"
-        assert parsed.raw == response
-
-    def test_extracts_multiple_memories(self):
-        """Parse response with multiple memories."""
-        response = """That's interesting background!
-
-<memory>{"memories": [
-    {"content": "Works at fintech startup", "category": "fact"},
-    {"content": "Uses PostgreSQL", "category": "preference"}
-]}</memory>"""
-
-        parsed = parse_response_with_memory(response)
-
-        assert len(parsed.memories) == 2
-        assert parsed.memories[0]["content"] == "Works at fintech startup"
-        assert parsed.memories[1]["content"] == "Uses PostgreSQL"
-
-    def test_handles_empty_memories(self):
-        """Parse response with no memories."""
-        response = """Hello! How can I help?
-
-<memory>{"memories": []}</memory>"""
-
-        parsed = parse_response_with_memory(response)
-
-        assert "Hello! How can I help?" in parsed.content
-        assert len(parsed.memories) == 0
-
-    def test_handles_no_memory_block(self):
-        """Parse response without memory block."""
-        response = "Just a normal response without memory."
-
-        parsed = parse_response_with_memory(response)
-
-        assert parsed.content == response
-        assert len(parsed.memories) == 0
-
-    def test_handles_malformed_json(self):
-        """Parse response with invalid JSON in memory block."""
-        response = """Some response.
-
-<memory>this is not valid json</memory>"""
-
-        parsed = parse_response_with_memory(response)
-
-        assert "Some response" in parsed.content
-        assert len(parsed.memories) == 0  # Gracefully handles error
-
-    def test_case_insensitive_tags(self):
-        """Memory tags should be case-insensitive."""
-        response = """Response here.
-
-<MEMORY>{"memories": [{"content": "Test", "category": "fact"}]}</MEMORY>"""
-
-        parsed = parse_response_with_memory(response)
-
-        assert len(parsed.memories) == 1
-
-    def test_memory_block_in_middle(self):
-        """Memory block can appear anywhere in response."""
-        response = """First part.
-
-<memory>{"memories": [{"content": "Test", "category": "fact"}]}</memory>
-
-More content after."""
-
-        parsed = parse_response_with_memory(response)
-
-        assert len(parsed.memories) == 1
-        assert "First part" in parsed.content
-        assert "More content after" in parsed.content
-
-
-class TestInjectMemoryInstruction:
-    """Test injection of memory instruction into messages."""
-
-    def test_appends_to_existing_system_prompt(self):
-        """Instruction appended to existing system message."""
-        messages = [
-            {"role": "system", "content": "You are helpful."},
-            {"role": "user", "content": "Hello"},
-        ]
-
-        result = inject_memory_instruction(messages, short=True)
-
-        assert len(result) == 2
-        assert result[0]["role"] == "system"
-        assert "You are helpful." in result[0]["content"]
-        assert "memory" in result[0]["content"].lower()
-
-    def test_creates_system_prompt_if_missing(self):
-        """Creates system message if none exists."""
-        messages = [
-            {"role": "user", "content": "Hello"},
-        ]
-
-        result = inject_memory_instruction(messages, short=True)
-
-        assert len(result) == 2
-        assert result[0]["role"] == "system"
-        assert "memory" in result[0]["content"].lower()
-
-    def test_does_not_modify_original(self):
-        """Original messages list is not modified."""
-        messages = [
-            {"role": "system", "content": "Original prompt."},
-            {"role": "user", "content": "Hello"},
-        ]
-        original_content = messages[0]["content"]
-
-        inject_memory_instruction(messages, short=True)
-
-        assert messages[0]["content"] == original_content
-
-    def test_short_vs_long_instruction(self):
-        """Short instruction is shorter than full instruction."""
-        messages = [{"role": "user", "content": "Hello"}]
-
-        short = inject_memory_instruction(messages, short=True)
-        long = inject_memory_instruction(messages, short=False)
-
-        assert len(short[0]["content"]) < len(long[0]["content"])
-
-    def test_instruction_contains_required_format(self):
-        """Instruction explains the memory format."""
-        messages = [{"role": "user", "content": "Hello"}]
-
-        result = inject_memory_instruction(messages, short=False)
-        content = result[0]["content"]
-
-        assert "<memory>" in content
-        assert "memories" in content
-        assert "category" in content
-
-
-class TestParsedResponse:
-    """Test ParsedResponse dataclass."""
-
-    def test_dataclass_fields(self):
-        """ParsedResponse has expected fields."""
-        parsed = ParsedResponse(
-            content="Hello",
-            memories=[{"content": "Test", "category": "fact"}],
-            raw="Hello\n<memory>...</memory>",
-        )
-
-        assert parsed.content == "Hello"
-        assert len(parsed.memories) == 1
-        assert parsed.raw == "Hello\n<memory>...</memory>"
-
-
-class TestMemoryInstructions:
-    """Test memory instruction prompts."""
-
-    def test_short_instruction_contains_essentials(self):
-        """Short instruction has minimum required info."""
-        assert "<memory>" in MEMORY_INSTRUCTION_SHORT
-        assert "memories" in MEMORY_INSTRUCTION_SHORT
-        assert "category" in MEMORY_INSTRUCTION_SHORT
-
-    def test_full_instruction_more_detailed(self):
-        """Full instruction has categories explained."""
-        assert "preference" in MEMORY_INSTRUCTION
-        assert "fact" in MEMORY_INSTRUCTION
-        assert "context" in MEMORY_INSTRUCTION
-        assert "Greetings" in MEMORY_INSTRUCTION or "greeting" in MEMORY_INSTRUCTION.lower()

tests/test_memory/test_store.py

@@ -1,278 +0,0 @@
-"""Tests for SQLite memory store.
-
-100% REAL SQLite - no mocks! These tests use actual SQLite
-databases in temp directories for realistic testing.
-"""
-
-from __future__ import annotations
-
-from headroom.memory.store import Memory, PendingExtraction, SQLiteMemoryStore
-
-
-class TestMemorySaveAndSearch:
-    """Test basic save and search operations."""
-
-    def test_save_and_search_finds_match(self, temp_db):
-        """Real SQLite, real FTS5, real queries."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="User prefers Python", category="preference"))
-
-        results = store.search("alice", "python", top_k=5)
-
-        assert len(results) == 1
-        assert "Python" in results[0].content
-
-    def test_search_no_results_for_unrelated_query(self, temp_db):
-        """Search returns empty when no matches."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="User prefers Python"))
-
-        results = store.search("alice", "javascript", top_k=5)
-
-        assert len(results) == 0
-
-    def test_search_respects_top_k_limit(self, temp_db):
-        """Search returns at most top_k results."""
-        store = SQLiteMemoryStore(temp_db)
-
-        for i in range(10):
-            store.save("alice", Memory(content=f"Python fact number {i}"))
-
-        results = store.search("alice", "python", top_k=3)
-
-        assert len(results) == 3
-
-    def test_save_preserves_all_fields(self, temp_db):
-        """All memory fields are preserved through save/search."""
-        store = SQLiteMemoryStore(temp_db)
-
-        original = Memory(
-            content="User prefers vim",
-            category="preference",
-            importance=0.9,
-            metadata={"source": "chat"},
-        )
-        store.save("alice", original)
-
-        results = store.search("alice", "vim", top_k=1)
-
-        assert len(results) == 1
-        retrieved = results[0]
-        assert retrieved.content == original.content
-        assert retrieved.category == original.category
-        assert retrieved.importance == original.importance
-        assert retrieved.metadata == original.metadata
-
-
-class TestUserIsolation:
-    """Test that memories are isolated by user_id."""
-
-    def test_users_have_separate_memories(self, temp_db):
-        """Memories are isolated by user_id."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="Likes Python programming"))
-        store.save("bob", Memory(content="Likes JavaScript programming"))
-
-        # Search for content that's actually in the memories
-        alice_results = store.search("alice", "Python", top_k=10)
-        bob_results = store.search("bob", "JavaScript", top_k=10)
-
-        # Each user should only see their own memories
-        assert len(alice_results) == 1
-        assert "Python" in alice_results[0].content
-
-        assert len(bob_results) == 1
-        assert "JavaScript" in bob_results[0].content
-
-    def test_get_all_returns_only_user_memories(self, temp_db):
-        """get_all only returns memories for the specified user."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="Alice memory 1"))
-        store.save("alice", Memory(content="Alice memory 2"))
-        store.save("bob", Memory(content="Bob memory"))
-
-        alice_memories = store.get_all("alice")
-        bob_memories = store.get_all("bob")
-
-        assert len(alice_memories) == 2
-        assert len(bob_memories) == 1
-
-
-class TestMemoryDeletion:
-    """Test deletion operations."""
-
-    def test_delete_specific_memory(self, temp_db):
-        """Delete removes a specific memory."""
-        store = SQLiteMemoryStore(temp_db)
-
-        mem = Memory(content="To be deleted")
-        store.save("alice", mem)
-
-        result = store.delete("alice", mem.id)
-
-        assert result is True
-        assert len(store.get_all("alice")) == 0
-
-    def test_delete_nonexistent_returns_false(self, temp_db):
-        """Delete returns False for nonexistent memory."""
-        store = SQLiteMemoryStore(temp_db)
-
-        result = store.delete("alice", "nonexistent-id")
-
-        assert result is False
-
-    def test_clear_removes_all_user_memories(self, temp_db):
-        """Clear removes all memories for a user."""
-        store = SQLiteMemoryStore(temp_db)
-
-        for i in range(5):
-            store.save("alice", Memory(content=f"Memory {i}"))
-        store.save("bob", Memory(content="Bob's memory"))
-
-        count = store.clear("alice")
-
-        assert count == 5
-        assert len(store.get_all("alice")) == 0
-        assert len(store.get_all("bob")) == 1  # Bob's memory untouched
-
-
-class TestMemoryStats:
-    """Test statistics operations."""
-
-    def test_stats_counts_memories(self, temp_db):
-        """Stats returns correct count."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="Mem 1", category="preference"))
-        store.save("alice", Memory(content="Mem 2", category="fact"))
-        store.save("alice", Memory(content="Mem 3", category="fact"))
-
-        stats = store.stats("alice")
-
-        assert stats["total"] == 3
-        assert stats["categories"]["preference"] == 1
-        assert stats["categories"]["fact"] == 2
-
-    def test_stats_empty_user(self, temp_db):
-        """Stats for user with no memories."""
-        store = SQLiteMemoryStore(temp_db)
-
-        stats = store.stats("alice")
-
-        assert stats["total"] == 0
-        assert stats["categories"] == {}
-
-
-class TestPendingExtractions:
-    """Test pending extraction queue for crash recovery."""
-
-    def test_queue_and_retrieve_pending(self, temp_db):
-        """Queue and retrieve pending extractions."""
-        store = SQLiteMemoryStore(temp_db)
-
-        pending = PendingExtraction(
-            user_id="alice",
-            query="What's your favorite language?",
-            response="I prefer Python for data science.",
-        )
-        store.queue_extraction(pending)
-
-        retrieved = store.get_pending_extractions(limit=10)
-
-        assert len(retrieved) == 1
-        assert retrieved[0].user_id == "alice"
-        assert retrieved[0].query == pending.query
-        assert retrieved[0].response == pending.response
-        assert retrieved[0].status == "pending"
-
-    def test_update_extraction_status(self, temp_db):
-        """Update status of pending extraction."""
-        store = SQLiteMemoryStore(temp_db)
-
-        pending = PendingExtraction(user_id="alice", query="Q", response="R")
-        store.queue_extraction(pending)
-
-        store.update_extraction_status(pending.id, "processing")
-
-        # Should not appear in pending list anymore
-        pending_list = store.get_pending_extractions(status="pending")
-        processing_list = store.get_pending_extractions(status="processing")
-
-        assert len(pending_list) == 0
-        assert len(processing_list) == 1
-
-    def test_delete_extraction(self, temp_db):
-        """Delete completed extraction."""
-        store = SQLiteMemoryStore(temp_db)
-
-        pending = PendingExtraction(user_id="alice", query="Q", response="R")
-        store.queue_extraction(pending)
-
-        store.delete_extraction(pending.id)
-
-        assert len(store.get_pending_extractions(limit=10)) == 0
-
-    def test_pending_fifo_order(self, temp_db):
-        """Pending extractions returned in FIFO order."""
-        store = SQLiteMemoryStore(temp_db)
-
-        for i in range(5):
-            store.queue_extraction(
-                PendingExtraction(user_id="alice", query=f"Q{i}", response=f"R{i}")
-            )
-
-        retrieved = store.get_pending_extractions(limit=3)
-
-        assert len(retrieved) == 3
-        assert retrieved[0].query == "Q0"
-        assert retrieved[1].query == "Q1"
-        assert retrieved[2].query == "Q2"
-
-
-class TestFTS5Features:
-    """Test FTS5 full-text search features."""
-
-    def test_phrase_search(self, temp_db):
-        """FTS5 supports phrase search with _raw: prefix."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="User prefers dark mode"))
-        store.save("alice", Memory(content="User is in dark times"))
-
-        # Exact phrase match using raw FTS5 syntax
-        results = store.search("alice", '_raw:"dark mode"', top_k=5)
-
-        assert len(results) == 1
-        assert "dark mode" in results[0].content
-
-    def test_prefix_search(self, temp_db):
-        """FTS5 supports prefix search with _raw: prefix."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="User loves Python programming"))
-        store.save("alice", Memory(content="User loves JavaScript"))
-
-        # Prefix search with * using raw FTS5 syntax
-        results = store.search("alice", "_raw:Pyth*", top_k=5)
-
-        assert len(results) == 1
-        assert "Python" in results[0].content
-
-    def test_boolean_and(self, temp_db):
-        """FTS5 supports boolean AND with _raw: prefix."""
-        store = SQLiteMemoryStore(temp_db)
-
-        store.save("alice", Memory(content="User prefers Python"))
-        store.save("alice", Memory(content="User prefers dark mode"))
-        store.save("alice", Memory(content="User prefers Python and dark mode"))
-
-        # Boolean AND using raw FTS5 syntax
-        results = store.search("alice", "_raw:Python AND dark", top_k=5)
-
-        assert len(results) == 1
-        assert "Python" in results[0].content
-        assert "dark" in results[0].content

tests/test_memory/test_wrapper.py

@@ -1,375 +0,0 @@
-"""Tests for memory wrapper integration.
-
-Tests the full with_memory() flow with mocked LLM clients.
-"""
-
-from __future__ import annotations
-
-import time
-
-from headroom.memory.store import Memory
-from headroom.memory.wrapper import with_memory
-
-
-class TestWithMemoryBasic:
-    """Test basic with_memory() functionality."""
-
-    def test_one_line_integration(self, temp_db, mock_openai_client, mock_extractor):
-        """One-line integration works."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-        )
-
-        response = client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "Hello"}],
-        )
-
-        assert response.choices[0].message.content == "Hello!"
-
-    def test_forwards_all_kwargs(self, temp_db, mock_openai_client, mock_extractor):
-        """All kwargs are forwarded to underlying client."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-        )
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "test"}],
-            temperature=0.5,
-            max_tokens=100,
-        )
-
-        call = mock_openai_client.chat.completions.calls[0]
-        assert call["model"] == "gpt-4o"
-        assert call["temperature"] == 0.5
-        assert call["max_tokens"] == 100
-
-
-class TestMemoryInjection:
-    """Test memory injection into messages."""
-
-    def test_injects_memory_into_user_message(self, temp_db, mock_openai_client, mock_extractor):
-        """Memory is injected into user message, not system prompt."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        # Pre-populate memory with content that will match the query
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="User prefers Python for coding", category="preference"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        # Use a query that will match the memory content
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[
-                {"role": "system", "content": "You are helpful."},
-                {"role": "user", "content": "What Python framework?"},
-            ],
-        )
-
-        # Check what was sent to the "API"
-        call = mock_openai_client.chat.completions.calls[0]
-        messages = call["messages"]
-
-        # System prompt should be UNCHANGED (for caching)
-        assert messages[0]["content"] == "You are helpful."
-
-        # User message should have context prepended
-        assert "<context>" in messages[1]["content"]
-        assert "Python" in messages[1]["content"]
-        assert "What Python framework?" in messages[1]["content"]
-
-    def test_preserves_system_prompt_exactly(self, temp_db, mock_openai_client, mock_extractor):
-        """System prompt is preserved exactly for caching."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="Some memory"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        original_system = "You are a helpful assistant. Always be concise."
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[
-                {"role": "system", "content": original_system},
-                {"role": "user", "content": "test"},
-            ],
-        )
-
-        call = mock_openai_client.chat.completions.calls[0]
-        assert call["messages"][0]["content"] == original_system
-
-    def test_no_injection_when_no_memories(self, temp_db, mock_openai_client, mock_extractor):
-        """No injection when user has no memories."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-        )
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "Hello"}],
-        )
-
-        call = mock_openai_client.chat.completions.calls[0]
-        # Message should be unchanged
-        assert call["messages"][0]["content"] == "Hello"
-        assert "<context>" not in call["messages"][0]["content"]
-
-    def test_respects_top_k(self, temp_db, mock_openai_client, mock_extractor):
-        """Only top_k memories are injected."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        for i in range(10):
-            store.save("alice", Memory(content=f"Python fact {i}"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-            top_k=3,
-        )
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "Python question"}],
-        )
-
-        call = mock_openai_client.chat.completions.calls[0]
-        content = call["messages"][0]["content"]
-
-        # Should have exactly 3 memories (top_k=3)
-        assert content.count("Python fact") == 3
-
-
-class TestBackgroundExtraction:
-    """Test background memory extraction."""
-
-    def test_queues_for_extraction(self, temp_db, mock_openai_client, mock_extractor):
-        """Conversation is queued for extraction after response."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-        mock_openai_client.chat.completions.set_response("I'll remember that!")
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-        )
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "I prefer Python"}],
-        )
-
-        # Wait for background worker
-        time.sleep(0.1)
-
-        # Check extraction was scheduled
-        # The mock extractor records batch calls
-        assert len(mock_extractor.batch_calls) >= 0  # May not have processed yet
-
-    def test_extracts_from_original_message(self, temp_db, mock_openai_client, mock_extractor):
-        """Extraction uses original message (without injected context)."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="Existing memory"))
-
-        mock_extractor.set_batch_response({"alice": [Memory(content="New fact", category="fact")]})
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        client.chat.completions.create(
-            model="gpt-4o",
-            messages=[{"role": "user", "content": "I like vim"}],
-        )
-
-        # Wait for background worker to process
-        time.sleep(1.5)
-
-        # The extractor should have been called with original message
-        # (not the one with <context> injected)
-        if mock_extractor.batch_calls:
-            batch = mock_extractor.batch_calls[0]
-            _, query, _ = batch[0]
-            assert "<context>" not in query
-
-
-class TestMemoryAPI:
-    """Test direct memory API access."""
-
-    def test_memory_search(self, temp_db, mock_openai_client, mock_extractor):
-        """client.memory.search() works."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="Likes Python"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        results = client.memory.search("Python")
-
-        assert len(results) == 1
-        assert "Python" in results[0].content
-
-    def test_memory_add(self, temp_db, mock_openai_client, mock_extractor):
-        """client.memory.add() works."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-        )
-
-        memory = client.memory.add("User prefers dark mode", category="preference")
-
-        assert memory.content == "User prefers dark mode"
-        assert memory.category == "preference"
-
-        # Verify it was saved
-        all_memories = client.memory.get_all()
-        assert len(all_memories) == 1
-
-    def test_memory_clear(self, temp_db, mock_openai_client, mock_extractor):
-        """client.memory.clear() works."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="Memory 1"))
-        store.save("alice", Memory(content="Memory 2"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        count = client.memory.clear()
-
-        assert count == 2
-        assert len(client.memory.get_all()) == 0
-
-    def test_memory_stats(self, temp_db, mock_openai_client, mock_extractor):
-        """client.memory.stats() works."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-        store.save("alice", Memory(content="Pref", category="preference"))
-        store.save("alice", Memory(content="Fact 1", category="fact"))
-        store.save("alice", Memory(content="Fact 2", category="fact"))
-
-        client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        stats = client.memory.stats()
-
-        assert stats["total"] == 3
-        assert stats["categories"]["preference"] == 1
-        assert stats["categories"]["fact"] == 2
-
-
-class TestMultiUser:
-    """Test multi-user isolation."""
-
-    def test_users_have_separate_memories(self, temp_db, mock_openai_client, mock_extractor):
-        """Different users have isolated memories."""
-        mock_openai_client.__class__.__module__ = "openai.resources"
-
-        from headroom.memory.store import SQLiteMemoryStore
-
-        store = SQLiteMemoryStore(temp_db)
-
-        # Create two wrapped clients for different users
-        alice_client = with_memory(
-            mock_openai_client,
-            user_id="alice",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        bob_client = with_memory(
-            mock_openai_client,
-            user_id="bob",
-            db_path=temp_db,
-            _extractor=mock_extractor,
-            _store=store,
-        )
-
-        # Add memories for each user
-        alice_client.memory.add("Alice's preference")
-        bob_client.memory.add("Bob's preference")
-
-        # Each should only see their own
-        assert len(alice_client.memory.get_all()) == 1
-        assert len(bob_client.memory.get_all()) == 1
-        assert "Alice" in alice_client.memory.get_all()[0].content
-        assert "Bob" in bob_client.memory.get_all()[0].content

uv.lock

@@ -914,7 +914,7 @@ wheels = [
 
 [[package]]
 name = "headroom-ai"
-version = "0.2.15"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "litellm" },
@@ -2080,7 +2080,7 @@ name = "nvidia-cudnn-cu12"
 version = "9.10.2.21"
 source = { registry = "https://pypi.netflix.net/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://pypi.netflix.net/packages/18753584630/nvidia_cudnn_cu12-9.10.2.21-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:c9132cc3f8958447b4910a1720036d9eff5928cc3179b0a51fb6d167c6cc87d8", size = 705026878 },
@@ -2092,7 +2092,7 @@ name = "nvidia-cufft-cu12"
 version = "11.3.3.83"
 source = { registry = "https://pypi.netflix.net/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://pypi.netflix.net/packages/18511525802/nvidia_cufft_cu12-11.3.3.83-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:848ef7224d6305cdb2a4df928759dca7b1201874787083b6e7550dd6765ce69a", size = 193109211 },
@@ -2122,9 +2122,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.7.3.90"
 source = { registry = "https://pypi.netflix.net/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
-    { name = "nvidia-cusparse-cu12" },
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cusparse-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://pypi.netflix.net/packages/18511526071/nvidia_cusolver_cu12-11.7.3.90-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:db9ed69dbef9715071232caa9b69c52ac7de3a95773c2db65bdba85916e4e5c0", size = 267229841 },
@@ -2136,7 +2136,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.5.8.93"
 source = { registry = "https://pypi.netflix.net/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://pypi.netflix.net/packages/18511526166/nvidia_cusparse_cu12-12.5.8.93-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:9b6c161cb130be1a07a27ea6923df8141f3c295852f4b260c65f18f3e0a091dc", size = 288117129 },