From f16dda579b7d1a552534be1d9c8f6ab4b2ee7b92 Mon Sep 17 00:00:00 2001
From: Robert Allen <zircote@gmail.com>
Date: Sat, 27 Dec 2025 16:37:58 -0500
Subject: [PATCH 1/4] docs: add memory retrieval improvements spec
 (SPEC-2025-12-27-002)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive specification for improving memory retrieval accuracy
from 65% to 90%+ through hybrid search, entity indexing, temporal
indexing, and LLM-powered query expansion.

Key documents:
- REQUIREMENTS.md: 4 P0, 4 P1, 3 P2 requirements
- ARCHITECTURE.md: 5 new components, schema v5
- IMPLEMENTATION_PLAN.md: 5 phases, 21 tasks
- DECISIONS.md: 10 ADRs including RRF, FTS5 BM25, spaCy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../ARCHITECTURE.md                           | 548 ++++++++++++++++++
 .../CHANGELOG.md                              |  41 ++
 .../DECISIONS.md                              | 352 +++++++++++
 .../IMPLEMENTATION_PLAN.md                    | 514 ++++++++++++++++
 .../PROGRESS.md                               |  96 +++
 .../README.md                                 |  59 ++
 .../REQUIREMENTS.md                           | 241 ++++++++
 7 files changed, 1851 insertions(+)
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/ARCHITECTURE.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/CHANGELOG.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/DECISIONS.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/IMPLEMENTATION_PLAN.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/README.md
 create mode 100644 docs/spec/active/2025-12-27-memory-retrieval-improvements/REQUIREMENTS.md

diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/ARCHITECTURE.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/ARCHITECTURE.md
new file mode 100644
index 00000000..d5d52d22
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/ARCHITECTURE.md
@@ -0,0 +1,548 @@
+---
+document_type: architecture
+project_id: SPEC-2025-12-27-002
+version: 1.0.0
+last_updated: 2025-12-27T18:00:00Z
+status: draft
+---
+
+# Memory Retrieval Performance Improvements - Technical Architecture
+
+## System Overview
+
+This architecture extends the existing git-notes-memory retrieval system with four new capabilities: hybrid search, entity indexing, temporal indexing, and query expansion. The design follows the established patterns of the codebase (service layer, schema migrations, observability integration) while adding new components that compose with existing infrastructure.
+
+### Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                              RecallService (Extended)                            │
+│  ┌─────────────┐   ┌─────────────────┐   ┌──────────────┐   ┌───────────────┐  │
+│  │ Query       │──▶│  Query          │──▶│ Retrieval    │──▶│ Result        │  │
+│  │ Parser      │   │  Expander       │   │ Orchestrator │   │ Merger        │  │
+│  └─────────────┘   │  (LLM, opt-in)  │   └──────────────┘   └───────────────┘  │
+│                    └─────────────────┘          │                   ▲          │
+│                                                 │                   │          │
+│                    ┌────────────────────────────┼───────────────────┘          │
+│                    ▼                            ▼                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                         Search Strategy Layer                            │   │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │   │
+│  │  │ Vector       │  │ BM25         │  │ Entity       │  │ Temporal    │  │   │
+│  │  │ Search       │  │ Search       │  │ Matcher      │  │ Filter      │  │   │
+│  │  │ (existing)   │  │ (existing)   │  │ (NEW)        │  │ (NEW)       │  │   │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘  └─────────────┘  │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
+│                    │                            │                               │
+│                    ▼                            ▼                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                         RRF Fusion Engine (NEW)                          │   │
+│  │  - Combines rankings from Vector, BM25, Entity                           │   │
+│  │  - Configurable k parameter and weights                                  │   │
+│  │  - Observability: latency, score distributions                           │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                              Index Layer (Extended)                              │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ memories        │  │ vec_memories    │  │ memories_fts    │                  │
+│  │ (existing)      │  │ (existing)      │  │ (existing)      │                  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘                  │
+│                                                                                  │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ entities        │  │ memory_entities │  │ temporal_refs   │                  │
+│  │ (NEW)           │  │ (NEW)           │  │ (NEW)           │                  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+1. **Additive Extension**: All new components are additive; no changes to existing APIs
+2. **Composition over Modification**: New strategies compose with existing search engines
+3. **Graceful Degradation**: Each new capability degrades gracefully if dependencies unavailable
+4. **Schema Migration**: New tables added via migration v5, following existing pattern
+5. **Opt-in LLM**: Query expansion requires explicit enablement to avoid latency impact
+
+## Component Design
+
+### Component 1: HybridSearchEngine
+
+- **Purpose**: Orchestrate multiple search strategies and combine results using RRF
+- **Responsibilities**:
+  - Execute vector and BM25 searches in parallel
+  - Apply entity and temporal boosting/filtering
+  - Combine rankings using Reciprocal Rank Fusion
+- **Interfaces**:
+  - `search(query, k, mode, entity_boost, date_from, date_to) -> List[MemoryResult]`
+- **Dependencies**: SearchEngine (existing), EntityMatcher, TemporalFilter
+- **Technology**: Python, asyncio for parallel execution
+- **Location**: `src/git_notes_memory/index/hybrid_search.py`
+
+```python
+@dataclass(frozen=True)
+class HybridSearchConfig:
+    """Configuration for hybrid search behavior."""
+    rrf_k: int = 60  # RRF constant (higher = less aggressive rank fusion)
+    vector_weight: float = 0.5  # Weight for vector search (0-1)
+    bm25_weight: float = 0.5  # Weight for BM25 search (0-1)
+    entity_boost: float = 1.5  # Multiplier for entity matches
+    enable_parallel: bool = True  # Parallel execution of strategies
+```
+
+### Component 2: EntityExtractor
+
+- **Purpose**: Extract named entities from memory content during ingestion
+- **Responsibilities**:
+  - Parse memory content for entities (PERSON, PROJECT, TECHNOLOGY, FILE, ORG)
+  - Store entity-memory mappings
+  - Provide query-time entity matching
+- **Interfaces**:
+  - `extract(content: str) -> List[Entity]`
+  - `match_query(query: str) -> List[Entity]`
+- **Dependencies**: spaCy (optional), regex fallbacks
+- **Technology**: spaCy `en_core_web_sm`, custom regex patterns
+- **Location**: `src/git_notes_memory/retrieval/entity_extractor.py`
+
+```python
+class Entity:
+    """Extracted entity with type and span information."""
+    text: str  # Normalized entity text
+    type: EntityType  # PERSON, PROJECT, TECHNOLOGY, FILE, ORG
+    start: int  # Character offset in source
+    end: int  # Character offset end
+    confidence: float  # Extraction confidence (0-1)
+```
+
+**Entity Detection Strategy**:
+1. **spaCy NER** (if available): PERSON, ORG, GPE, PRODUCT
+2. **Regex patterns** (always): File paths, URLs, code references, @mentions
+3. **Keyword lists** (configurable): Technology names, project identifiers
+
+### Component 3: TemporalExtractor
+
+- **Purpose**: Parse and normalize temporal references in content and queries
+- **Responsibilities**:
+  - Extract dates from memory content
+  - Resolve relative dates ("last week", "in December")
+  - Provide date-range filtering
+- **Interfaces**:
+  - `extract(content: str) -> List[TemporalRef]`
+  - `resolve_query(query: str, reference_date: datetime) -> DateRange`
+- **Dependencies**: dateparser
+- **Technology**: dateparser library, custom parsing
+- **Location**: `src/git_notes_memory/retrieval/temporal_extractor.py`
+
+```python
+@dataclass(frozen=True)
+class TemporalRef:
+    """Extracted temporal reference with normalized dates."""
+    text: str  # Original text ("last week", "December 15th")
+    start_date: datetime | None  # Normalized start
+    end_date: datetime | None  # Normalized end (for ranges)
+    granularity: str  # "day", "week", "month", "year"
+    confidence: float  # Parsing confidence
+```
+
+### Component 4: QueryExpander
+
+- **Purpose**: Use LLM to expand ambiguous queries for better recall
+- **Responsibilities**:
+  - Detect when expansion is beneficial
+  - Generate expanded query terms using LLM
+  - Cache expansions for repeated queries
+- **Interfaces**:
+  - `expand(query: str, context: Optional[str]) -> ExpandedQuery`
+- **Dependencies**: LLMClient (existing subconsciousness module)
+- **Technology**: Existing LLM infrastructure (Anthropic/OpenAI/Ollama)
+- **Location**: `src/git_notes_memory/retrieval/query_expander.py`
+
+```python
+@dataclass(frozen=True)
+class ExpandedQuery:
+    """Query with LLM-generated expansions."""
+    original: str
+    expanded_terms: tuple[str, ...]  # Additional search terms
+    synonyms: tuple[str, ...]  # Alternative phrasings
+    entities_mentioned: tuple[str, ...]  # Extracted entity hints
+    intent: str  # Detected query intent
+```
+
+### Component 5: RRFFusionEngine
+
+- **Purpose**: Combine rankings from multiple search strategies
+- **Responsibilities**:
+  - Implement Reciprocal Rank Fusion algorithm
+  - Support weighted combination of sources
+  - Provide score normalization
+- **Interfaces**:
+  - `fuse(rankings: List[List[MemoryResult]], weights: List[float]) -> List[MemoryResult]`
+- **Dependencies**: None (pure algorithm)
+- **Location**: `src/git_notes_memory/index/rrf_fusion.py`
+
+**RRF Algorithm**:
+```
+RRF_score(d) = Σ (weight_i / (k + rank_i(d)))
+```
+Where:
+- `d` is a document (memory)
+- `k` is the fusion constant (default 60)
+- `rank_i(d)` is the rank of d in source i
+- `weight_i` is the weight of source i
+
+## Data Design
+
+### Data Models
+
+#### New Tables (Schema v5)
+
+```sql
+-- Entity registry: canonical entities across all memories
+CREATE TABLE entities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    text TEXT NOT NULL,           -- Normalized entity text
+    type TEXT NOT NULL,           -- PERSON, PROJECT, TECHNOLOGY, FILE, ORG
+    canonical_form TEXT,          -- Canonical version (for linking)
+    first_seen TEXT NOT NULL,     -- ISO timestamp
+    mention_count INTEGER DEFAULT 1,
+    UNIQUE(text, type)
+);
+CREATE INDEX idx_entities_text ON entities(text);
+CREATE INDEX idx_entities_type ON entities(type);
+CREATE INDEX idx_entities_canonical ON entities(canonical_form);
+
+-- Entity-to-memory mapping (many-to-many)
+CREATE TABLE memory_entities (
+    memory_id TEXT NOT NULL REFERENCES memories(id),
+    entity_id INTEGER NOT NULL REFERENCES entities(id),
+    span_start INTEGER,           -- Character offset
+    span_end INTEGER,             -- Character offset
+    confidence REAL DEFAULT 1.0,
+    PRIMARY KEY (memory_id, entity_id, span_start)
+);
+CREATE INDEX idx_memory_entities_memory ON memory_entities(memory_id);
+CREATE INDEX idx_memory_entities_entity ON memory_entities(entity_id);
+
+-- Temporal references in memories
+CREATE TABLE temporal_refs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    memory_id TEXT NOT NULL REFERENCES memories(id),
+    text TEXT NOT NULL,           -- Original text ("last week")
+    start_date TEXT,              -- ISO date (nullable for fuzzy refs)
+    end_date TEXT,                -- ISO date (nullable for points)
+    granularity TEXT,             -- day, week, month, year
+    span_start INTEGER,           -- Character offset
+    span_end INTEGER,             -- Character offset
+    confidence REAL DEFAULT 1.0
+);
+CREATE INDEX idx_temporal_refs_memory ON temporal_refs(memory_id);
+CREATE INDEX idx_temporal_refs_dates ON temporal_refs(start_date, end_date);
+```
+
+### Data Flow
+
+```
+CAPTURE FLOW (Extended):
+┌──────────┐    ┌─────────────┐    ┌─────────────┐    ┌──────────────┐
+│ Memory   │───▶│ Entity      │───▶│ Temporal    │───▶│ Index        │
+│ Content  │    │ Extractor   │    │ Extractor   │    │ Service      │
+└──────────┘    └─────────────┘    └─────────────┘    └──────────────┘
+                     │                   │                   │
+                     ▼                   ▼                   ▼
+              ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+              │ entities     │    │ temporal_refs│    │ memories     │
+              │ memory_ents  │    │              │    │ vec_memories │
+              └──────────────┘    └──────────────┘    └──────────────┘
+
+SEARCH FLOW (Hybrid):
+┌──────────┐    ┌─────────────┐    ┌─────────────────────────────────────┐
+│ Query    │───▶│ Query       │───▶│ Parallel Strategy Execution         │
+│          │    │ Parser      │    │ ┌─────────┬─────────┬─────────────┐ │
+└──────────┘    │ + Expander  │    │ │ Vector  │ BM25    │ Entity      │ │
+                │ (optional)  │    │ │ Search  │ Search  │ Matcher     │ │
+                └─────────────┘    │ └─────────┴─────────┴─────────────┘ │
+                                   └─────────────────────────────────────┘
+                                                    │
+                                                    ▼
+                                   ┌─────────────────────────────────────┐
+                                   │ RRF Fusion + Temporal Filter        │
+                                   └─────────────────────────────────────┘
+                                                    │
+                                                    ▼
+                                   ┌─────────────────────────────────────┐
+                                   │ Ranked Results                       │
+                                   └─────────────────────────────────────┘
+```
+
+### Storage Strategy
+
+- **Primary Store**: SQLite (existing index.db)
+- **Entity Index**: New tables in same database
+- **Temporal Index**: New table in same database
+- **Query Expansion Cache**: LRU cache in memory (TTL-based eviction)
+- **No new files**: All data in existing index.db
+
+## API Design
+
+### API Overview
+
+- **Style**: Python API (no REST/GraphQL)
+- **Backward Compatible**: All new parameters are optional with sensible defaults
+- **Configuration**: Environment variables + runtime config objects
+
+### Extended RecallService API
+
+```python
+class RecallService:
+    """Extended recall service with hybrid search capabilities."""
+
+    def search(
+        self,
+        query: str,
+        k: int = 10,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+        min_similarity: float | None = None,
+        # NEW: Hybrid search parameters
+        mode: Literal["hybrid", "vector", "bm25"] = "hybrid",
+        entity_boost: bool = True,
+        date_from: datetime | str | None = None,
+        date_to: datetime | str | None = None,
+        expand_query: bool = False,  # Opt-in LLM expansion
+        rrf_config: HybridSearchConfig | None = None,
+    ) -> list[MemoryResult]:
+        """Search memories with hybrid retrieval.
+
+        Args:
+            query: Search query (natural language)
+            k: Maximum results to return
+            namespace: Filter by namespace
+            spec: Filter by spec
+            domain: Filter by domain ("user" or "project")
+            min_similarity: Minimum similarity threshold (vector mode)
+            mode: Search strategy ("hybrid", "vector", "bm25")
+            entity_boost: Boost results matching query entities
+            date_from: Filter to memories after this date
+            date_to: Filter to memories before this date
+            expand_query: Use LLM to expand query (adds latency)
+            rrf_config: Custom RRF configuration
+
+        Returns:
+            List of MemoryResult with combined relevance scores
+        """
+```
+
+### New Configuration Classes
+
+```python
+@dataclass(frozen=True)
+class HybridSearchConfig:
+    """Configuration for hybrid search behavior."""
+    rrf_k: int = 60
+    vector_weight: float = 0.5
+    bm25_weight: float = 0.5
+    entity_boost_factor: float = 1.5
+    enable_parallel: bool = True
+    expansion_cache_ttl: int = 3600  # seconds
+
+
+@dataclass(frozen=True)
+class EntityExtractorConfig:
+    """Configuration for entity extraction."""
+    use_spacy: bool = True  # Fall back to regex if False/unavailable
+    spacy_model: str = "en_core_web_sm"
+    custom_patterns: dict[str, list[str]] = field(default_factory=dict)
+    min_confidence: float = 0.5
+
+
+@dataclass(frozen=True)
+class QueryExpansionConfig:
+    """Configuration for LLM query expansion."""
+    enabled: bool = False  # Opt-in
+    llm_provider: str = "anthropic"  # or "openai", "ollama"
+    model: str | None = None  # Uses provider default
+    max_expansions: int = 5
+    cache_enabled: bool = True
+```
+
+## Integration Points
+
+### Internal Integrations
+
+| System | Integration Type | Purpose |
+|--------|-----------------|---------|
+| IndexService | Direct call | Access existing search methods |
+| SearchEngine | Direct call | Existing vector/text search |
+| EmbeddingService | Direct call | Query embedding generation |
+| LLMClient | Direct call | Query expansion (subconsciousness) |
+| SchemaManager | Direct call | Schema v5 migration |
+| MetricsCollector | Direct call | Telemetry |
+
+### External Integrations
+
+| Service | Integration Type | Purpose |
+|---------|-----------------|---------|
+| spaCy | Library import | NER for entity extraction |
+| dateparser | Library import | Temporal parsing |
+
+## Security Design
+
+### Entity Extraction Security
+
+- Entity extraction runs AFTER security filtering (secrets, PII)
+- Extracted entities are from already-sanitized content
+- No raw content in entity tables (just normalized text)
+
+### LLM Query Expansion Security
+
+- Queries sent to LLM contain no memory content
+- Only the query text is sent
+- No PII leakage risk (queries are user-provided)
+
+### Data Protection
+
+- All new tables follow existing access patterns
+- No additional encryption needed (same security model as existing tables)
+
+## Performance Considerations
+
+### Expected Load
+
+- **Queries per session**: 10-100 (typical Claude session)
+- **Concurrent queries**: 1 (single-threaded Claude)
+- **Memory count**: 100-10,000 (typical repo)
+- **Entity count**: 10-100× memory count
+
+### Performance Targets
+
+| Metric | Target | Strategy |
+|--------|--------|----------|
+| Vector search | <30ms | Existing (no change) |
+| BM25 search | <10ms | FTS5 (existing) |
+| Entity lookup | <5ms | Indexed by entity_id |
+| RRF fusion | <1ms | In-memory algorithm |
+| Total hybrid | <50ms | Parallel execution |
+| With expansion | <200ms | LLM latency dominated |
+
+### Optimization Strategies
+
+1. **Parallel Execution**: Vector and BM25 searches run concurrently
+2. **Early Termination**: Stop BM25 at k×3 results for fusion
+3. **Entity Index**: B-tree index on entity text for fast lookup
+4. **Expansion Cache**: LRU cache with TTL for repeated queries
+5. **Lazy spaCy Load**: Load spaCy model on first use, not import
+
+## Reliability & Operations
+
+### Failure Modes
+
+| Failure | Impact | Recovery |
+|---------|--------|----------|
+| spaCy unavailable | Reduced entity accuracy | Fall back to regex patterns |
+| dateparser fails | No temporal filtering | Use timestamp-only |
+| LLM unavailable | No query expansion | Skip expansion, use raw query |
+| BM25 search fails | Reduced precision | Fall back to vector-only |
+| Entity table missing | No entity boost | Skip entity matching |
+
+### Monitoring & Alerting
+
+New metrics (via existing observability):
+- `retrieval_search_latency_ms{strategy=hybrid|vector|bm25}`
+- `retrieval_entity_matches_total`
+- `retrieval_temporal_filters_total`
+- `retrieval_query_expansions_total`
+- `retrieval_rrf_fusion_latency_ms`
+
+### Graceful Degradation
+
+```python
+# Degradation cascade
+if spacy_available:
+    entities = spacy_extract(content)
+else:
+    entities = regex_extract(content)  # Always available
+
+if dateparser_available:
+    temporal = dateparser_extract(query)
+else:
+    temporal = timestamp_only(query)  # Parse ISO dates
+
+if llm_available and expand_query:
+    query = llm_expand(query)
+# else: use original query (always works)
+```
+
+## Testing Strategy
+
+### Unit Testing
+
+- Entity extraction: Test all entity types, edge cases
+- Temporal parsing: Test relative dates, ranges, edge cases
+- RRF fusion: Test ranking combination, edge cases
+- Query expansion: Mock LLM responses
+
+### Integration Testing
+
+- Hybrid search end-to-end
+- Schema migration v4 → v5
+- Entity indexing during capture
+- Benchmark harness regression
+
+### Performance Testing
+
+- Latency benchmarks: 1K, 10K, 100K memories
+- Entity index size vs memory count
+- Query expansion cache hit rates
+
+## Deployment Considerations
+
+### Environment Requirements
+
+- Python 3.11+
+- SQLite with FTS5 support (standard)
+- Optional: spaCy model download (~12MB)
+
+### Configuration Management
+
+Environment variables (new):
+```bash
+# Feature flags
+RETRIEVAL_HYBRID_ENABLED=true
+RETRIEVAL_ENTITY_EXTRACTION_ENABLED=true
+RETRIEVAL_TEMPORAL_ENABLED=true
+RETRIEVAL_QUERY_EXPANSION_ENABLED=false  # Opt-in
+
+# Tuning
+RETRIEVAL_RRF_K=60
+RETRIEVAL_VECTOR_WEIGHT=0.5
+RETRIEVAL_BM25_WEIGHT=0.5
+RETRIEVAL_ENTITY_BOOST=1.5
+
+# spaCy
+RETRIEVAL_SPACY_MODEL=en_core_web_sm
+```
+
+### Migration Path
+
+1. Deploy v5 schema migration (additive, safe)
+2. Enable entity extraction (captures only)
+3. Backfill entities for existing memories (optional, background)
+4. Enable hybrid search (default mode)
+5. Enable query expansion (opt-in)
+
+### Rollback Plan
+
+- Schema v5 tables can coexist with v4 (additive)
+- Set `RETRIEVAL_HYBRID_ENABLED=false` to disable
+- Existing `mode="vector"` parameter as escape hatch
+
+## Future Considerations
+
+1. **Graph-based retrieval**: Entity relationships for multi-hop queries
+2. **Cross-memory reasoning**: LLM synthesis of related memories
+3. **Active learning**: User feedback to improve extraction/ranking
+4. **Distributed indexing**: Multi-repo federation
+5. **Streaming search**: Progressive result delivery
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/CHANGELOG.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/CHANGELOG.md
new file mode 100644
index 00000000..a93f2735
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/CHANGELOG.md
@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this specification will be documented in this file.
+
+## [1.0.0] - 2025-12-27
+
+### Added
+- Complete requirements specification (REQUIREMENTS.md)
+  - 4 P0 requirements: Hybrid Search, Entity Indexing, Temporal Indexing, Query Expansion
+  - 4 P1 requirements: Entity Boost, Mode Selection, Temporal Reasoning, Telemetry
+  - 3 P2 requirements: Entity Autocomplete, Semantic Linking, Hierarchical Search
+- Technical architecture design (ARCHITECTURE.md)
+  - 5 new components: HybridSearchEngine, EntityExtractor, TemporalExtractor, QueryExpander, RRFFusionEngine
+  - Schema v5 with entities, memory_entities, temporal_refs tables
+  - Integration with existing SearchEngine and LLMClient
+- Implementation plan with 5 phases, 21 tasks (IMPLEMENTATION_PLAN.md)
+  - Phase 1: Foundation (schema + RRF)
+  - Phase 2: Hybrid Search (BM25 + Vector fusion)
+  - Phase 3: Entity Indexing (NER + entity boost)
+  - Phase 4: Temporal Indexing (date parsing + filtering)
+  - Phase 5: Query Expansion (LLM-powered)
+- 10 Architecture Decision Records (DECISIONS.md)
+  - ADR-001: RRF for fusion
+  - ADR-002: Add deps to [consolidation] extra
+  - ADR-003: Graceful degradation
+  - ADR-004: Parallel search execution
+  - ADR-005: Use FTS5 BM25
+  - ADR-006: Entity extraction at capture time
+  - ADR-007: Opt-in LLM expansion
+  - ADR-008: Single SQLite database
+  - ADR-009: Regex fallback for entities
+  - ADR-010: dateparser for temporal
+
+### Research Conducted
+- Analyzed existing codebase: SearchEngine, SchemaManager, RecallService
+- Reviewed benchmark harness GitNotesAdapter integration
+- Researched RRF, spaCy NER, dateparser, hybrid search patterns
+
+### Baseline
+- Benchmark accuracy: 65% (13/20 questions)
+- Target accuracy: 90%+ (18/20 questions)
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/DECISIONS.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/DECISIONS.md
new file mode 100644
index 00000000..d4fa3518
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/DECISIONS.md
@@ -0,0 +1,352 @@
+---
+document_type: decisions
+project_id: SPEC-2025-12-27-002
+---
+
+# Memory Retrieval Performance Improvements - Architecture Decision Records
+
+## ADR-001: Use Reciprocal Rank Fusion for Hybrid Search
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: User, Claude
+
+### Context
+
+We need to combine rankings from multiple search strategies (vector similarity, BM25, entity matching). Several fusion approaches exist: weighted linear combination, CombSUM, CombMNZ, and Reciprocal Rank Fusion (RRF).
+
+### Decision
+
+Use Reciprocal Rank Fusion (RRF) with configurable k parameter (default 60).
+
+```
+RRF_score(d) = Σ (weight_i / (k + rank_i(d)))
+```
+
+### Consequences
+
+**Positive:**
+- RRF is parameter-light (just k and weights)
+- Well-studied in IR literature
+- Works well when sources have different score distributions
+- Easy to add new sources (just another ranking list)
+
+**Negative:**
+- Requires computing full rankings from each source
+- May not be optimal when one source is clearly better for a query type
+- Fixed k may not be ideal for all query types
+
+### Alternatives Considered
+
+1. **Linear Score Combination**: Requires score normalization, sensitive to scale differences
+2. **CombSUM/CombMNZ**: More complex, requires tuning multiple parameters
+3. **Learning-to-Rank**: Requires training data, adds ML complexity
+
+---
+
+## ADR-002: Add Dependencies to [consolidation] Extra
+
+**Date**: 2025-12-27
+**Status**: Accepted (per user preference)
+**Deciders**: User
+
+### Context
+
+The new retrieval features require spaCy (for NER) and dateparser (for temporal parsing). These add ~20MB to install size. We could create a new `[retrieval]` extra or add to existing `[consolidation]`.
+
+### Decision
+
+Add spaCy and dateparser to the existing `[consolidation]` extra per user preference.
+
+```toml
+[project.optional-dependencies]
+consolidation = [
+    # ... existing deps ...
+    "spacy>=3.7",
+    "dateparser>=1.2",
+]
+```
+
+### Consequences
+
+**Positive:**
+- Single extra for advanced features (simpler user experience)
+- Users who want consolidation likely want advanced retrieval too
+- Fewer combinations to test
+
+**Negative:**
+- Users who only want consolidation get retrieval deps
+- Install size slightly larger for consolidation-only users
+
+### Alternatives Considered
+
+1. **New [retrieval] extra**: Cleaner separation but more complexity
+2. **Core dependencies**: Would bloat minimal install
+
+---
+
+## ADR-003: Graceful Degradation Without Optional Dependencies
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+spaCy and dateparser are optional. The library should work without them, with reduced functionality.
+
+### Decision
+
+Implement graceful degradation with fallbacks:
+- spaCy unavailable → use regex-only entity extraction
+- dateparser unavailable → use ISO date parsing only
+- LLM unavailable → skip query expansion
+
+### Consequences
+
+**Positive:**
+- Library always works, even without optional deps
+- Clear error messages when features degraded
+- Users can install deps as needed
+
+**Negative:**
+- Reduced accuracy without spaCy
+- More code paths to test
+- Need to document degradation behavior
+
+### Alternatives Considered
+
+1. **Hard dependency**: Would break minimal installs
+2. **Feature flags only**: Wouldn't catch missing deps gracefully
+
+---
+
+## ADR-004: Parallel Execution of Search Strategies
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+Hybrid search executes multiple strategies (vector, BM25, entity). These could run sequentially or in parallel.
+
+### Decision
+
+Execute vector and BM25 searches in parallel using asyncio or threading, with a fallback to sequential execution.
+
+### Consequences
+
+**Positive:**
+- Lower total latency (max(latencies) instead of sum)
+- Better utilization of I/O wait time
+- Configurable via `enable_parallel` flag
+
+**Negative:**
+- More complex error handling
+- SQLite connection management needs care
+- Debugging more complex
+
+### Alternatives Considered
+
+1. **Sequential only**: Simpler but slower
+2. **Always parallel**: No escape hatch for debugging
+
+---
+
+## ADR-005: Use FTS5 BM25 Instead of rank_bm25 Library
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+The codebase already has FTS5 configured (schema v4, PERF-H-005). We could use the existing FTS5 BM25 or add the rank_bm25 Python library.
+
+### Decision
+
+Use existing FTS5 BM25 implementation. No additional dependency.
+
+### Consequences
+
+**Positive:**
+- No new dependency
+- Already integrated with schema
+- Single index (not separate BM25 corpus)
+- FTS5 is highly optimized
+
+**Negative:**
+- Less control over BM25 parameters (k1, b)
+- Can't easily experiment with BM25L, BM25+
+
+### Alternatives Considered
+
+1. **rank_bm25 library**: More control but new dependency, separate index
+2. **bm25s (Numba-accelerated)**: Fast but heavy dependency
+
+---
+
+## ADR-006: Entity Extraction at Capture Time
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+Entities could be extracted at capture time (synchronous) or asynchronously (background job). The consolidation module already has background processing.
+
+### Decision
+
+Extract entities synchronously during capture, with timeout protection.
+
+### Consequences
+
+**Positive:**
+- Entities immediately available for search
+- Simpler architecture (no job queue)
+- Consistent with current capture flow
+
+**Negative:**
+- Adds latency to capture (~10-50ms)
+- spaCy model loaded on first capture
+
+### Alternatives Considered
+
+1. **Async extraction**: Lower capture latency but delayed searchability
+2. **Batch extraction**: Good for bulk, but delays individual captures
+
+---
+
+## ADR-007: Opt-In LLM Query Expansion
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+LLM query expansion adds significant latency (100-200ms). It should be optional.
+
+### Decision
+
+Make query expansion opt-in via `expand_query=False` default parameter.
+
+### Consequences
+
+**Positive:**
+- Default behavior is fast
+- Users explicitly opt into latency
+- Can enable globally via env var
+
+**Negative:**
+- Users may not discover the feature
+- Need good documentation
+
+### Alternatives Considered
+
+1. **Opt-out (on by default)**: Would surprise users with latency
+2. **Auto-detect ambiguous queries**: Complex, may misfire
+
+---
+
+## ADR-008: Single SQLite Database for All Tables
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+New tables (entities, memory_entities, temporal_refs) could go in the existing index.db or a separate database.
+
+### Decision
+
+Add new tables to existing index.db with foreign key relationships.
+
+### Consequences
+
+**Positive:**
+- Single file to manage
+- Atomic transactions across tables
+- Simpler backup/restore
+
+**Negative:**
+- Larger single file
+- All migrations in one sequence
+
+### Alternatives Considered
+
+1. **Separate retrieval.db**: Cleaner separation but complex joins
+2. **In-memory for entities**: Fast but no persistence
+
+---
+
+## ADR-009: Regex Fallback for Entity Extraction
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+spaCy is optional. We need a fallback for entity extraction.
+
+### Decision
+
+Implement comprehensive regex patterns for:
+- File paths (`/path/to/file.py`, `src/module/file.ts`)
+- URLs (`https://example.com`)
+- @mentions (`@username`)
+- Code references (`` `ClassName.method` ``)
+- Technology names (configurable list)
+
+### Consequences
+
+**Positive:**
+- Works without spaCy
+- Very fast (<1ms)
+- Good for technical entities (file paths, code)
+
+**Negative:**
+- Lower accuracy for PERSON, ORG
+- Needs manual pattern maintenance
+
+### Alternatives Considered
+
+1. **No fallback**: Would disable entity features without spaCy
+2. **Simple word tokenization**: Too noisy
+
+---
+
+## ADR-010: dateparser for Temporal Parsing
+
+**Date**: 2025-12-27
+**Status**: Proposed
+**Deciders**: Claude
+
+### Context
+
+We need to parse natural language dates ("last week", "in December"). Options: dateparser, dateutil, parsedatetime.
+
+### Decision
+
+Use dateparser library for its comprehensive language support and relative date handling.
+
+### Consequences
+
+**Positive:**
+- Handles relative dates well
+- Multi-language support (future)
+- Active maintenance
+
+**Negative:**
+- ~5MB dependency
+- Can be slow for complex expressions
+
+### Alternatives Considered
+
+1. **dateutil.parser**: Limited relative date support
+2. **parsedatetime**: Less maintained
+3. **Custom regex**: Limited and brittle
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/IMPLEMENTATION_PLAN.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/IMPLEMENTATION_PLAN.md
new file mode 100644
index 00000000..f00d9005
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/IMPLEMENTATION_PLAN.md
@@ -0,0 +1,514 @@
+---
+document_type: implementation_plan
+project_id: SPEC-2025-12-27-002
+version: 1.0.0
+last_updated: 2025-12-27T18:00:00Z
+status: draft
+---
+
+# Memory Retrieval Performance Improvements - Implementation Plan
+
+## Overview
+
+This implementation plan breaks down the retrieval improvements into 5 phases, prioritizing the highest-impact changes first. Each phase is independently deployable and testable, following the codebase's established patterns for schema migrations, service composition, and observability integration.
+
+## Team & Resources
+
+| Role | Responsibility | Allocation |
+|------|----------------|------------|
+| Claude Code Agent | All implementation | 100% |
+| User | Review, approval, benchmark validation | As needed |
+
+## Phase Summary
+
+| Phase | Focus | Key Deliverables | Dependencies |
+|-------|-------|------------------|--------------|
+| Phase 1: Foundation | Schema + RRF | Schema v5, RRF fusion engine | None |
+| Phase 2: Hybrid Search | BM25 + Vector fusion | HybridSearchEngine, RecallService extension | Phase 1 |
+| Phase 3: Entity Indexing | NER + Entity tables | EntityExtractor, entity-memory mapping | Phase 1 |
+| Phase 4: Temporal Indexing | Date parsing + filtering | TemporalExtractor, date-range search | Phase 1 |
+| Phase 5: Query Expansion | LLM-powered expansion | QueryExpander, caching | Phase 2 |
+
+---
+
+## Phase 1: Foundation
+
+**Goal**: Establish schema v5 and core RRF fusion algorithm
+**Prerequisites**: None
+**Exit Criteria**: Schema migration works, RRF produces correct rankings
+
+### Tasks
+
+#### Task 1.1: Schema v5 Migration
+
+- **Description**: Add new tables (entities, memory_entities, temporal_refs) via schema migration
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] Schema version bumped to 5
+  - [ ] `entities` table created with indexes
+  - [ ] `memory_entities` table created with foreign keys
+  - [ ] `temporal_refs` table created with date indexes
+  - [ ] Migration runs on fresh and existing databases
+  - [ ] Rollback tested (tables can be dropped without breaking v4)
+- **Files**:
+  - `src/git_notes_memory/index/schema_manager.py` - Add v5 migrations
+
+#### Task 1.2: RRF Fusion Engine
+
+- **Description**: Implement Reciprocal Rank Fusion algorithm
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] `RRFFusionEngine` class with `fuse()` method
+  - [ ] Configurable k parameter (default 60)
+  - [ ] Configurable weights per source
+  - [ ] Unit tests with known rankings
+  - [ ] Edge cases: empty lists, single source, ties
+- **Files**:
+  - `src/git_notes_memory/index/rrf_fusion.py` - New file
+  - `tests/index/test_rrf_fusion.py` - New test file
+
+#### Task 1.3: HybridSearchConfig Dataclass
+
+- **Description**: Create configuration dataclass for hybrid search
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] Frozen dataclass with all config parameters
+  - [ ] Environment variable loading
+  - [ ] Sensible defaults
+  - [ ] Integration with observability config pattern
+- **Files**:
+  - `src/git_notes_memory/retrieval/__init__.py` - New module
+  - `src/git_notes_memory/retrieval/config.py` - Config classes
+
+#### Task 1.4: Retrieval Module Scaffold
+
+- **Description**: Create the new `retrieval/` module structure
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] Module with `__init__.py` and lazy imports
+  - [ ] Factory functions for services
+  - [ ] Export in main `__init__.py`
+- **Files**:
+  - `src/git_notes_memory/retrieval/__init__.py`
+  - `src/git_notes_memory/retrieval/config.py`
+
+### Phase 1 Deliverables
+
+- [ ] Schema v5 migration in `schema_manager.py`
+- [ ] `RRFFusionEngine` with tests
+- [ ] `HybridSearchConfig` dataclass
+- [ ] `retrieval/` module scaffold
+
+### Phase 1 Exit Criteria
+
+- [ ] `make test` passes
+- [ ] Schema migration creates new tables
+- [ ] RRF fusion produces correct rankings for test data
+
+---
+
+## Phase 2: Hybrid Search
+
+**Goal**: Combine existing BM25 and vector search using RRF
+**Prerequisites**: Phase 1 complete
+**Exit Criteria**: Hybrid search returns combined rankings
+
+### Tasks
+
+#### Task 2.1: HybridSearchEngine
+
+- **Description**: Orchestrate vector + BM25 searches and combine with RRF
+- **Dependencies**: Task 1.2 (RRF)
+- **Acceptance Criteria**:
+  - [ ] `HybridSearchEngine` class with `search()` method
+  - [ ] Parallel execution of vector and BM25 searches
+  - [ ] RRF fusion of results
+  - [ ] Observability: latency metrics per strategy
+  - [ ] Mode selection: "hybrid", "vector", "bm25"
+- **Files**:
+  - `src/git_notes_memory/index/hybrid_search.py` - New file
+  - `tests/index/test_hybrid_search.py` - New test file
+
+#### Task 2.2: Extend SearchEngine
+
+- **Description**: Add method to return rankings (not just results) for RRF
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] `search_vector_ranked()` returns (memory, rank, score)
+  - [ ] `search_text_ranked()` returns (memory, rank, score)
+  - [ ] Existing methods unchanged (backward compatible)
+- **Files**:
+  - `src/git_notes_memory/index/search_engine.py` - Extend
+
+#### Task 2.3: Extend RecallService
+
+- **Description**: Add hybrid search parameters to RecallService.search()
+- **Dependencies**: Task 2.1
+- **Acceptance Criteria**:
+  - [ ] New parameters: `mode`, `rrf_config`
+  - [ ] Default mode: "hybrid" (or configurable via env)
+  - [ ] Backward compatible: existing calls work unchanged
+  - [ ] Telemetry: search mode in spans
+- **Files**:
+  - `src/git_notes_memory/recall.py` - Extend search()
+
+#### Task 2.4: Benchmark Validation
+
+- **Description**: Run benchmark harness to measure improvement
+- **Dependencies**: Task 2.3
+- **Acceptance Criteria**:
+  - [ ] Run memory-benchmark-harness
+  - [ ] Compare hybrid vs vector-only accuracy
+  - [ ] Document results in PROGRESS.md
+- **Files**:
+  - None (validation only)
+
+### Phase 2 Deliverables
+
+- [ ] `HybridSearchEngine` with RRF fusion
+- [ ] Extended `SearchEngine` with ranking methods
+- [ ] Extended `RecallService` with hybrid parameters
+- [ ] Benchmark comparison: vector-only vs hybrid
+
+### Phase 2 Exit Criteria
+
+- [ ] Hybrid search produces different (better) rankings than vector-only
+- [ ] All existing tests pass
+- [ ] Benchmark accuracy improved
+
+---
+
+## Phase 3: Entity Indexing
+
+**Goal**: Extract and index named entities for entity-aware search
+**Prerequisites**: Phase 1 complete
+**Exit Criteria**: Entities indexed during capture, entity boost in search
+
+### Tasks
+
+#### Task 3.1: EntityExtractor Base
+
+- **Description**: Create entity extraction framework with regex fallback
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] `EntityExtractor` class with `extract()` method
+  - [ ] Entity types: PERSON, PROJECT, TECHNOLOGY, FILE, ORG
+  - [ ] Regex patterns for file paths, URLs, @mentions
+  - [ ] Works without spaCy (pure regex mode)
+- **Files**:
+  - `src/git_notes_memory/retrieval/entity_extractor.py`
+  - `tests/retrieval/test_entity_extractor.py`
+
+#### Task 3.2: spaCy Integration
+
+- **Description**: Add spaCy NER for higher-quality entity extraction
+- **Dependencies**: Task 3.1
+- **Acceptance Criteria**:
+  - [ ] Lazy load spaCy model (avoid import-time cost)
+  - [ ] Graceful degradation if spaCy unavailable
+  - [ ] Map spaCy entity types to our types
+  - [ ] Combine spaCy + regex results
+- **Files**:
+  - `src/git_notes_memory/retrieval/entity_extractor.py` - Extend
+  - `pyproject.toml` - Add spacy to [consolidation] extra
+
+#### Task 3.3: Entity Persistence
+
+- **Description**: Store entities and entity-memory mappings in SQLite
+- **Dependencies**: Task 1.1 (schema), Task 3.1
+- **Acceptance Criteria**:
+  - [ ] `EntityStore` class for CRUD operations
+  - [ ] Deduplication: same entity text+type = single row
+  - [ ] Bulk insert for efficiency
+  - [ ] Query by entity text or type
+- **Files**:
+  - `src/git_notes_memory/retrieval/entity_store.py`
+  - `tests/retrieval/test_entity_store.py`
+
+#### Task 3.4: Capture Integration
+
+- **Description**: Extract and store entities during memory capture
+- **Dependencies**: Task 3.3
+- **Acceptance Criteria**:
+  - [ ] `CaptureService.capture()` triggers entity extraction
+  - [ ] Entities stored after successful capture
+  - [ ] Extraction failure doesn't block capture
+  - [ ] Telemetry: entity count per capture
+- **Files**:
+  - `src/git_notes_memory/capture.py` - Extend
+
+#### Task 3.5: Entity Matcher
+
+- **Description**: Match query entities and boost results
+- **Dependencies**: Task 3.3
+- **Acceptance Criteria**:
+  - [ ] `EntityMatcher` class with `match_query()` method
+  - [ ] Extract entities from query
+  - [ ] Find memories mentioning matched entities
+  - [ ] Return entity boost scores for RRF
+- **Files**:
+  - `src/git_notes_memory/retrieval/entity_matcher.py`
+  - `tests/retrieval/test_entity_matcher.py`
+
+#### Task 3.6: Entity Boost in Hybrid Search
+
+- **Description**: Add entity matching as RRF source
+- **Dependencies**: Task 2.1, Task 3.5
+- **Acceptance Criteria**:
+  - [ ] Entity matcher integrated into HybridSearchEngine
+  - [ ] `entity_boost` parameter controls behavior
+  - [ ] Entity matches added to RRF fusion
+- **Files**:
+  - `src/git_notes_memory/index/hybrid_search.py` - Extend
+
+### Phase 3 Deliverables
+
+- [ ] `EntityExtractor` with regex + spaCy
+- [ ] `EntityStore` for persistence
+- [ ] `EntityMatcher` for query-time matching
+- [ ] Entity extraction in capture pipeline
+- [ ] Entity boost in hybrid search
+
+### Phase 3 Exit Criteria
+
+- [ ] Entities extracted and stored during capture
+- [ ] Entity-specific queries show improved accuracy
+- [ ] All tests pass
+
+---
+
+## Phase 4: Temporal Indexing
+
+**Goal**: Parse temporal references and enable date-range filtering
+**Prerequisites**: Phase 1 complete
+**Exit Criteria**: Temporal queries ("when did we") return date-aware results
+
+### Tasks
+
+#### Task 4.1: TemporalExtractor
+
+- **Description**: Extract and normalize temporal references from content
+- **Dependencies**: None
+- **Acceptance Criteria**:
+  - [ ] `TemporalExtractor` class with `extract()` method
+  - [ ] Parse absolute dates ("December 15, 2025")
+  - [ ] Parse relative dates ("last week", "yesterday")
+  - [ ] Graceful degradation without dateparser
+- **Files**:
+  - `src/git_notes_memory/retrieval/temporal_extractor.py`
+  - `tests/retrieval/test_temporal_extractor.py`
+  - `pyproject.toml` - Add dateparser to [consolidation] extra
+
+#### Task 4.2: Temporal Persistence
+
+- **Description**: Store temporal references in SQLite
+- **Dependencies**: Task 1.1 (schema), Task 4.1
+- **Acceptance Criteria**:
+  - [ ] Store start_date, end_date, granularity
+  - [ ] Index on dates for range queries
+  - [ ] Bulk insert support
+- **Files**:
+  - `src/git_notes_memory/retrieval/temporal_store.py`
+  - `tests/retrieval/test_temporal_store.py`
+
+#### Task 4.3: Capture Integration
+
+- **Description**: Extract and store temporal refs during capture
+- **Dependencies**: Task 4.2
+- **Acceptance Criteria**:
+  - [ ] Temporal extraction in capture pipeline
+  - [ ] Extraction failure doesn't block capture
+  - [ ] Telemetry: temporal ref count
+- **Files**:
+  - `src/git_notes_memory/capture.py` - Extend
+
+#### Task 4.4: Query Temporal Resolution
+
+- **Description**: Resolve temporal expressions in queries
+- **Dependencies**: Task 4.1
+- **Acceptance Criteria**:
+  - [ ] `resolve_query()` method for query-time parsing
+  - [ ] Handle "when did we", "last month", etc.
+  - [ ] Return date range for filtering
+- **Files**:
+  - `src/git_notes_memory/retrieval/temporal_extractor.py` - Extend
+
+#### Task 4.5: Date-Range Filtering
+
+- **Description**: Add date_from/date_to parameters to search
+- **Dependencies**: Task 4.4
+- **Acceptance Criteria**:
+  - [ ] `RecallService.search(date_from=, date_to=)` parameters
+  - [ ] Filter applied after RRF fusion
+  - [ ] Natural language dates resolved automatically
+- **Files**:
+  - `src/git_notes_memory/recall.py` - Extend
+  - `src/git_notes_memory/index/hybrid_search.py` - Extend
+
+### Phase 4 Deliverables
+
+- [ ] `TemporalExtractor` with dateparser
+- [ ] Temporal reference storage
+- [ ] Query temporal resolution
+- [ ] Date-range filtering in search
+
+### Phase 4 Exit Criteria
+
+- [ ] Temporal refs extracted during capture
+- [ ] "When did we" queries return chronologically relevant results
+- [ ] Date range filters work correctly
+
+---
+
+## Phase 5: Query Expansion
+
+**Goal**: LLM-powered query expansion for better recall
+**Prerequisites**: Phase 2 complete
+**Exit Criteria**: Ambiguous queries return improved results with expansion
+
+### Tasks
+
+#### Task 5.1: QueryExpander
+
+- **Description**: Use LLMClient to expand queries
+- **Dependencies**: None (uses existing LLMClient)
+- **Acceptance Criteria**:
+  - [ ] `QueryExpander` class with `expand()` method
+  - [ ] Uses existing subconsciousness LLMClient
+  - [ ] Configurable prompt template
+  - [ ] Returns expanded terms, synonyms, entity hints
+- **Files**:
+  - `src/git_notes_memory/retrieval/query_expander.py`
+  - `tests/retrieval/test_query_expander.py`
+
+#### Task 5.2: Expansion Caching
+
+- **Description**: Cache query expansions to avoid repeated LLM calls
+- **Dependencies**: Task 5.1
+- **Acceptance Criteria**:
+  - [ ] LRU cache with configurable TTL
+  - [ ] Cache key: normalized query
+  - [ ] Telemetry: cache hit rate
+- **Files**:
+  - `src/git_notes_memory/retrieval/query_expander.py` - Extend
+
+#### Task 5.3: Search Integration
+
+- **Description**: Add `expand_query` parameter to RecallService
+- **Dependencies**: Task 5.1
+- **Acceptance Criteria**:
+  - [ ] `expand_query=True` triggers LLM expansion
+  - [ ] Expanded terms used in BM25 search
+  - [ ] Default: False (opt-in)
+  - [ ] Telemetry: expansion latency
+- **Files**:
+  - `src/git_notes_memory/recall.py` - Extend
+  - `src/git_notes_memory/index/hybrid_search.py` - Extend
+
+#### Task 5.4: Expansion Prompt Tuning
+
+- **Description**: Optimize expansion prompt for memory retrieval
+- **Dependencies**: Task 5.3
+- **Acceptance Criteria**:
+  - [ ] Test different prompt templates
+  - [ ] Measure impact on benchmark accuracy
+  - [ ] Document optimal prompt
+- **Files**:
+  - `src/git_notes_memory/retrieval/prompts/` - Prompt templates
+
+### Phase 5 Deliverables
+
+- [ ] `QueryExpander` with LLM integration
+- [ ] Expansion caching
+- [ ] `expand_query` parameter in search
+- [ ] Optimized expansion prompt
+
+### Phase 5 Exit Criteria
+
+- [ ] Query expansion improves recall for ambiguous queries
+- [ ] Cache prevents redundant LLM calls
+- [ ] Latency within targets (<200ms P95)
+
+---
+
+## Dependency Graph
+
+```
+Phase 1: Foundation (no deps)
+├── Task 1.1: Schema v5 ────────────────────────────┐
+├── Task 1.2: RRF Fusion ───────────┐               │
+├── Task 1.3: HybridSearchConfig    │               │
+└── Task 1.4: Retrieval scaffold    │               │
+                                    │               │
+Phase 2: Hybrid Search              │               │
+├── Task 2.1: HybridSearchEngine ◄──┘               │
+├── Task 2.2: Extend SearchEngine                   │
+├── Task 2.3: Extend RecallService ◄─ Task 2.1      │
+└── Task 2.4: Benchmark validation                  │
+                                                    │
+Phase 3: Entity Indexing                            │
+├── Task 3.1: EntityExtractor base                  │
+├── Task 3.2: spaCy integration ◄─── Task 3.1       │
+├── Task 3.3: Entity persistence ◄── Task 1.1 ──────┤
+├── Task 3.4: Capture integration ◄─ Task 3.3       │
+├── Task 3.5: Entity matcher ◄────── Task 3.3       │
+└── Task 3.6: Entity boost ◄──────── Task 2.1, 3.5  │
+                                                    │
+Phase 4: Temporal Indexing                          │
+├── Task 4.1: TemporalExtractor                     │
+├── Task 4.2: Temporal persistence ◄─ Task 1.1 ─────┘
+├── Task 4.3: Capture integration ◄── Task 4.2
+├── Task 4.4: Query resolution ◄───── Task 4.1
+└── Task 4.5: Date-range filter ◄──── Task 4.4
+
+Phase 5: Query Expansion
+├── Task 5.1: QueryExpander
+├── Task 5.2: Expansion caching ◄─── Task 5.1
+├── Task 5.3: Search integration ◄── Task 5.1, 2.1
+└── Task 5.4: Prompt tuning
+```
+
+## Risk Mitigation Tasks
+
+| Risk | Mitigation Task | Phase |
+|------|-----------------|-------|
+| spaCy model size | Use en_core_web_sm (12MB), document optional install | Phase 3 |
+| LLM latency | Implement caching, make opt-in | Phase 5 |
+| RRF parameter tuning | Benchmark with multiple k values | Phase 2 |
+| Schema migration | Test on copy of production index | Phase 1 |
+
+## Testing Checklist
+
+- [ ] Unit tests for RRF fusion
+- [ ] Unit tests for EntityExtractor (regex + spaCy)
+- [ ] Unit tests for TemporalExtractor
+- [ ] Unit tests for QueryExpander (mock LLM)
+- [ ] Integration tests for HybridSearchEngine
+- [ ] Integration tests for entity capture pipeline
+- [ ] Integration tests for temporal capture pipeline
+- [ ] E2E test: benchmark harness regression
+- [ ] Performance test: latency at 1K, 10K memories
+
+## Documentation Tasks
+
+- [ ] Update CLAUDE.md with new env vars
+- [ ] Update README.md with retrieval section
+- [ ] Add retrieval module docstrings
+- [ ] Document entity extraction patterns
+
+## Launch Checklist
+
+- [ ] All tests passing (>85% coverage)
+- [ ] Schema migration tested on real data
+- [ ] Benchmark shows improvement (target: 90%+)
+- [ ] Telemetry verified in Grafana
+- [ ] Feature flags tested
+- [ ] Rollback procedure documented
+
+## Post-Launch
+
+- [ ] Monitor search latency P50/P95
+- [ ] Track entity extraction accuracy
+- [ ] Gather user feedback on result quality
+- [ ] Tune RRF parameters based on real usage
+- [ ] Consider entity disambiguation (future)
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
new file mode 100644
index 00000000..08af30cb
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
@@ -0,0 +1,96 @@
+---
+document_type: progress
+project_id: SPEC-2025-12-27-002
+project_name: "Memory Retrieval Performance Improvements"
+started: 2025-12-27T19:00:00Z
+last_updated: 2025-12-27T19:00:00Z
+---
+
+# Implementation Progress
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| **Phase** | 1 of 5 |
+| **Tasks Completed** | 0/21 |
+| **Progress** | 0% |
+| **Status** | in-progress |
+
+## Phase 1: Foundation
+
+| Task | Status | Started | Completed | Notes |
+|------|--------|---------|-----------|-------|
+| 1.1 Schema v5 Migration | pending | - | - | |
+| 1.2 RRF Fusion Engine | pending | - | - | |
+| 1.3 HybridSearchConfig | pending | - | - | |
+| 1.4 Retrieval Module Scaffold | pending | - | - | |
+
+**Phase Status**: pending
+**Phase Progress**: 0/4 tasks
+
+## Phase 2: Hybrid Search
+
+| Task | Status | Started | Completed | Notes |
+|------|--------|---------|-----------|-------|
+| 2.1 HybridSearchEngine | pending | - | - | |
+| 2.2 Extend SearchEngine | pending | - | - | |
+| 2.3 Extend RecallService | pending | - | - | |
+| 2.4 Benchmark Validation | pending | - | - | |
+
+**Phase Status**: pending
+**Phase Progress**: 0/4 tasks
+
+## Phase 3: Entity Indexing
+
+| Task | Status | Started | Completed | Notes |
+|------|--------|---------|-----------|-------|
+| 3.1 EntityExtractor Base | pending | - | - | |
+| 3.2 spaCy Integration | pending | - | - | |
+| 3.3 Entity Persistence | pending | - | - | |
+| 3.4 Capture Integration | pending | - | - | |
+| 3.5 Entity Matcher | pending | - | - | |
+| 3.6 Entity Boost in Hybrid Search | pending | - | - | |
+
+**Phase Status**: pending
+**Phase Progress**: 0/6 tasks
+
+## Phase 4: Temporal Indexing
+
+| Task | Status | Started | Completed | Notes |
+|------|--------|---------|-----------|-------|
+| 4.1 TemporalExtractor | pending | - | - | |
+| 4.2 Temporal Persistence | pending | - | - | |
+| 4.3 Capture Integration | pending | - | - | |
+| 4.4 Query Temporal Resolution | pending | - | - | |
+| 4.5 Date-Range Filtering | pending | - | - | |
+
+**Phase Status**: pending
+**Phase Progress**: 0/5 tasks
+
+## Phase 5: Query Expansion
+
+| Task | Status | Started | Completed | Notes |
+|------|--------|---------|-----------|-------|
+| 5.1 QueryExpander | pending | - | - | |
+| 5.2 Expansion Caching | pending | - | - | |
+| 5.3 Search Integration | pending | - | - | |
+| 5.4 Expansion Prompt Tuning | pending | - | - | |
+
+**Phase Status**: pending
+**Phase Progress**: 0/4 tasks
+
+## Divergences from Plan
+
+_None yet._
+
+## Benchmark Results
+
+| Checkpoint | Score | Change | Date |
+|------------|-------|--------|------|
+| Baseline | 65% (13/20) | - | 2025-12-27 |
+
+## Notes
+
+- Implementation started: 2025-12-27
+- Target: 90%+ accuracy (18/20 questions)
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/README.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/README.md
new file mode 100644
index 00000000..85aceebd
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/README.md
@@ -0,0 +1,59 @@
+---
+project_id: SPEC-2025-12-27-002
+project_name: "Memory Retrieval Performance Improvements"
+slug: memory-retrieval-improvements
+status: in-progress
+created: 2025-12-27T18:00:00Z
+approved: 2025-12-27T19:00:00Z
+started: 2025-12-27T19:00:00Z
+completed: null
+expires: 2026-03-27T18:00:00Z
+superseded_by: null
+tags: [retrieval, search, indexing, performance, bm25, vector, llm]
+stakeholders: []
+benchmark_baseline: 65%
+benchmark_target: 90%+
+phases: 5
+tasks: 21
+adrs: 10
+---
+
+# Memory Retrieval Performance Improvements
+
+## Overview
+
+Improve memory retrieval accuracy from the current 65% benchmark score to 90%+ through advanced indexing, hybrid search, and LLM-assisted query expansion.
+
+## Problem Statement
+
+Current memory-benchmark-harness validation shows:
+- **Baseline (no-memory)**: 0/20 correct (0%)
+- **git-notes-memory**: 13/20 correct (65%)
+- **Gap**: 7 questions failing completely
+
+The current vector-only search with sentence-transformers (all-MiniLM-L6-v2) lacks:
+1. Named entity awareness for specific queries
+2. Keyword matching for exact terms
+3. Temporal reasoning for date-based questions
+4. Query understanding and expansion
+
+## Proposed Solutions
+
+1. **Entity-Aware Indexing**: Extract and index named entities (people, projects, technologies)
+2. **Hybrid Search (BM25 + Vector)**: Combine keyword and semantic search
+3. **Hierarchical Summaries**: Leverage consolidation for entity-centric summaries
+4. **Temporal Indexing**: Parse and normalize dates in memories
+5. **Query Expansion with LLM**: Expand queries before search
+
+## Key Documents
+
+- [REQUIREMENTS.md](./REQUIREMENTS.md) - Product Requirements Document
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - Technical Design
+- [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) - Phased Task Breakdown
+- [DECISIONS.md](./DECISIONS.md) - Architecture Decision Records
+- [RESEARCH_NOTES.md](./RESEARCH_NOTES.md) - Research Findings
+
+## Related Work
+
+- Previous spec: `docs/spec/completed/2025-12-25-llm-subconsciousness/` (LLM integration)
+- Related spec: `docs/spec/active/2025-12-27-memory-consolidation/` (consolidation pipeline)
diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/REQUIREMENTS.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/REQUIREMENTS.md
new file mode 100644
index 00000000..c2a768c4
--- /dev/null
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/REQUIREMENTS.md
@@ -0,0 +1,241 @@
+---
+document_type: requirements
+project_id: SPEC-2025-12-27-002
+version: 1.0.0
+last_updated: 2025-12-27T18:00:00Z
+status: draft
+---
+
+# Memory Retrieval Performance Improvements - Product Requirements Document
+
+## Executive Summary
+
+This specification defines improvements to the git-notes-memory library's retrieval system to increase benchmark accuracy from 65% to 90%+. The improvements include hybrid search (combining existing BM25 and vector search), entity-aware indexing, temporal query handling, and LLM-powered query expansion. All improvements are additive, maintaining backward compatibility with existing APIs while providing new capabilities for precision recall.
+
+## Problem Statement
+
+### The Problem
+
+The current memory retrieval system achieves 65% accuracy (13/20 correct) on the memory-benchmark-harness validation suite. Seven question types fail completely:
+
+1. **Entity-specific queries**: "What did John say about X?" - Vector search doesn't prioritize named entity matches
+2. **Temporal queries**: "When did we decide X?" - No temporal parsing or filtering
+3. **Exact term matching**: "What's our policy on ABC?" - Pure semantic search misses keyword relevance
+4. **Specificity queries**: Questions requiring precise term matching alongside semantic understanding
+
+### Impact
+
+- **Library users**: Cannot reliably retrieve specific memories, reducing trust and adoption
+- **Claude plugin users**: Contextual memory injection has gaps, limiting AI assistant effectiveness
+- **Benchmark credibility**: 65% accuracy is below competitive alternatives
+
+### Current State
+
+The codebase has foundational components that are underutilized:
+- **FTS5 with BM25**: Already exists in `search_engine.py` (PERF-H-005) but used as fallback, not combined with vector search
+- **Vector search**: sqlite-vec KNN search works well for semantic similarity
+- **LLM client**: Consolidation module has `LLMClient` for Anthropic/OpenAI/Ollama
+- **Schema migrations**: Version 4 infrastructure supports additive changes
+
+The problem is not missing components but missing **orchestration** - combining these capabilities for precision retrieval.
+
+## Goals and Success Criteria
+
+### Primary Goal
+
+Improve retrieval accuracy from 65% to 90%+ on the memory-benchmark-harness while maintaining sub-100ms average latency for typical queries.
+
+### Success Metrics
+
+| Metric | Current | Target | Measurement Method |
+|--------|---------|--------|-------------------|
+| Benchmark accuracy | 65% (13/20) | 90%+ (18/20) | memory-benchmark-harness validation |
+| Entity query recall | ~20% | 85%+ | Entity-specific question subset |
+| Temporal query recall | ~10% | 80%+ | Temporal question subset |
+| Exact term matching | ~40% | 90%+ | Keyword-critical question subset |
+| Average query latency | <50ms | <100ms | P50 latency in telemetry |
+| P95 query latency | <100ms | <200ms | P95 latency in telemetry |
+
+### Non-Goals (Explicit Exclusions)
+
+- **Graph-based retrieval**: Not adding full knowledge graph capabilities in v1
+- **Summarization during retrieval**: Consolidation handles this; retrieval returns raw memories
+- **Multi-modal search**: No image/audio memory support
+- **Real-time streaming**: Batch search only
+- **Breaking API changes**: All improvements are additive
+
+## User Analysis
+
+### Primary Users
+
+1. **Library Consumers (Python developers)**
+   - **Who**: Developers using git-notes-memory as a Python library
+   - **Needs**: Accurate, fast memory retrieval for application logic
+   - **Context**: Integration into larger applications, benchmarks, testing
+
+2. **Claude Plugin Users (via hooks)**
+   - **Who**: Claude Code users with the memory plugin installed
+   - **Needs**: Reliable context injection during coding sessions
+   - **Context**: Hook-triggered retrieval with tight latency budgets (<10ms hook overhead)
+
+3. **Benchmark Harness**
+   - **Who**: Automated validation suite
+   - **Needs**: Consistent, measurable retrieval accuracy
+   - **Context**: CI/CD validation, performance regression detection
+
+### User Stories
+
+1. **US-001**: As a library consumer, I want to search for memories about a specific person or project so that I can retrieve decisions and context related to that entity.
+
+2. **US-002**: As a library consumer, I want to ask "when did we decide X" and get temporally-relevant results so that I can understand the timeline of decisions.
+
+3. **US-003**: As a library consumer, I want exact term matching to take priority when my query contains specific identifiers so that I don't miss relevant memories.
+
+4. **US-004**: As a library consumer, I want the system to understand my query intent and expand it intelligently so that I get relevant results even when my query is ambiguous.
+
+5. **US-005**: As a Claude plugin user, I want retrieval to be fast enough that it doesn't noticeably slow down my coding session.
+
+6. **US-006**: As a library consumer, I want to configure the balance between speed and accuracy so that I can optimize for my use case.
+
+## Functional Requirements
+
+### Must Have (P0)
+
+| ID | Requirement | Rationale | Acceptance Criteria |
+|----|-------------|-----------|---------------------|
+| FR-001 | **Hybrid Search (BM25 + Vector)**: Combine existing FTS5 BM25 scores with vector similarity using Reciprocal Rank Fusion (RRF) | Improves exact term matching while preserving semantic understanding | - Given a query with both keywords and semantic meaning, When search is executed, Then results combine BM25 and vector rankings<br>- RRF k parameter configurable (default 60)<br>- Relative weighting configurable (default 0.5/0.5) |
+| FR-002 | **Entity-Aware Indexing**: Extract and index named entities (people, projects, technologies, files) from memory content | Enables entity-specific queries to filter or boost results | - Entities extracted on memory insertion<br>- Entity types: PERSON, PROJECT, TECHNOLOGY, FILE, ORG<br>- Entity-to-memory mapping stored in new table<br>- Query-time entity matching boosts relevance |
+| FR-003 | **Temporal Indexing**: Parse and normalize temporal references in memories and queries | Enables "when did we" queries and date-range filtering | - Dates extracted from memory content and timestamp<br>- Relative date queries ("last week", "in December") resolved<br>- New `search(..., date_from=, date_to=)` parameters |
+| FR-004 | **Query Expansion with LLM**: Use existing LLMClient to expand ambiguous queries before search | Improves recall for underspecified queries | - Optional, disabled by default (opt-in)<br>- Uses existing subconsciousness LLMClient<br>- Configurable expansion prompt<br>- Caches expansions for repeated queries |
+
+### Should Have (P1)
+
+| ID | Requirement | Rationale | Acceptance Criteria |
+|----|-------------|-----------|---------------------|
+| FR-101 | **Entity Boost Mode**: Query-time option to boost results containing query-mentioned entities | Fine-grained control over entity influence | - `search(..., entity_boost=True)` parameter<br>- Boost factor configurable |
+| FR-102 | **Search Mode Selection**: API to select search strategy (vector-only, bm25-only, hybrid) | Allows users to optimize for their use case | - `search(..., mode="hybrid"|"vector"|"bm25")` parameter<br>- Default: "hybrid" |
+| FR-103 | **Temporal Reasoning Mode**: LLM-powered answering for complex temporal queries | Handles "when" questions that need reasoning | - `search(..., mode="temporal")` for specialized handling<br>- Returns structured temporal response |
+| FR-104 | **Search Telemetry**: Metrics and traces for search operations | Debugging and optimization | - Latency histograms per search component<br>- Entity/temporal match rates<br>- RRF score distributions |
+
+### Nice to Have (P2)
+
+| ID | Requirement | Rationale | Acceptance Criteria |
+|----|-------------|-----------|---------------------|
+| FR-201 | **Entity Autocomplete**: Suggest entities as user types query | UX improvement for entity discovery | - Return entity suggestions for partial matches |
+| FR-202 | **Semantic Entity Linking**: Link entity mentions to canonical forms | Reduces entity fragmentation | - "John", "John Smith", "@johnsmith" → same entity |
+| FR-203 | **Hierarchical Entity Search**: Search by entity category | Browse memories by entity type | - `search(entity_type="PERSON")` filter |
+
+## Non-Functional Requirements
+
+### Performance
+
+- **P50 latency**: <100ms for hybrid search (vector + BM25 + entity boost)
+- **P95 latency**: <200ms for complex queries with LLM expansion
+- **Memory overhead**: <50MB additional for entity index on 10K memories
+- **Index build time**: <5ms per memory for entity/temporal extraction
+
+### Security
+
+- Entity extraction must not leak sensitive data (PII filtered per existing security subsystem)
+- LLM query expansion must not include raw memory content in prompts
+
+### Scalability
+
+- Index size linear with memory count (no exponential growth)
+- Entity index should support 100K+ entities efficiently
+
+### Reliability
+
+- Graceful degradation: if entity extraction fails, fall back to vector-only
+- Graceful degradation: if LLM unavailable, skip query expansion
+- All new features behind feature flags for rollback
+
+### Maintainability
+
+- New schema version (v5) with forward migration
+- All new tables follow existing naming conventions
+- Comprehensive test coverage (>85%)
+
+## Technical Constraints
+
+- **Python 3.11+**: Required by existing codebase
+- **SQLite + sqlite-vec**: Must use existing database, no new database dependencies
+- **Optional dependencies**: spaCy/dateparser added to `[consolidation]` extra per user preference
+- **LLM providers**: Use existing `LLMClient` (Anthropic, OpenAI, Ollama)
+- **Backward compatibility**: Existing `recall.search()` API unchanged; new parameters optional
+
+## Dependencies
+
+### Internal Dependencies
+
+- `git_notes_memory.index` - Search engine, schema manager
+- `git_notes_memory.embedding` - Embedding service
+- `git_notes_memory.subconsciousness.llm_client` - LLM integration
+- `git_notes_memory.security` - Secrets filtering for entity extraction
+
+### External Dependencies (New)
+
+| Package | Purpose | Extra |
+|---------|---------|-------|
+| `spacy>=3.7` | Named entity recognition | `[consolidation]` |
+| `en_core_web_sm` | spaCy model (lightweight) | Manual install |
+| `dateparser>=1.2` | Natural language date parsing | `[consolidation]` |
+| `rank_bm25>=0.2` | BM25 implementation (if needed beyond FTS5) | Optional |
+
+### Existing Dependencies (Already Available)
+
+- `sqlite-vec` - Vector similarity search
+- `sentence-transformers` - Embedding generation
+- FTS5 - Built into SQLite, already configured
+
+## Risks and Mitigations
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| spaCy model size (100MB+) | High | Medium | Use `en_core_web_sm` (12MB); provide instructions for minimal install |
+| LLM latency for query expansion | Medium | Medium | Cache expansions; make opt-in; async prefetch option |
+| Entity extraction accuracy | Medium | Medium | Supplement spaCy with regex patterns for technical entities |
+| RRF parameter tuning | Medium | Low | Provide sensible defaults; expose config for power users |
+| Schema migration complexity | Low | High | Test migration thoroughly; provide rollback script |
+| Temporal parsing edge cases | Medium | Low | Fall back to timestamp-only filtering on parse failure |
+
+## Open Questions
+
+- [ ] Should entity extraction run synchronously during capture or in background?
+- [ ] What's the optimal RRF k parameter for our use case? (Research suggests 60)
+- [ ] Should we support spaCy transformer models for higher accuracy? (Much larger)
+- [ ] How to handle entity disambiguation? (e.g., multiple "John"s)
+
+## Appendix
+
+### Glossary
+
+| Term | Definition |
+|------|------------|
+| BM25 | Best Matching 25 - probabilistic ranking function for keyword search |
+| RRF | Reciprocal Rank Fusion - algorithm to combine rankings from multiple sources |
+| NER | Named Entity Recognition - extracting entities (people, places, orgs) from text |
+| FTS5 | Full-Text Search 5 - SQLite's built-in full-text search engine |
+| sqlite-vec | SQLite extension for vector similarity search |
+
+### References
+
+- [sqlite-vec hybrid search](https://alexgarcia.xyz/blog/2024/sqlite-vec-hybrid-search/index.html)
+- [Reciprocal Rank Fusion paper](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)
+- [spaCy NER documentation](https://spacy.io/usage/linguistic-features#named-entities)
+- [dateparser documentation](https://dateparser.readthedocs.io/)
+- [Existing FTS5 implementation](src/git_notes_memory/index/search_engine.py:163-236)
+
+### Benchmark Baseline Data
+
+```
+Validation run: 2025-12-27
+Adapter: git-notes-memory v1.0.0
+Results: 13/20 correct (65%)
+
+Failed question types:
+- Entity-specific: 4/5 failed
+- Temporal: 3/3 failed
+- Exact term: 2/4 failed
+- Complex reasoning: 2/8 failed
+```

From 78dd019092618552ac31d85eab5c5a6ca040d337 Mon Sep 17 00:00:00 2001
From: Robert Allen <zircote@gmail.com>
Date: Sat, 27 Dec 2025 17:01:29 -0500
Subject: [PATCH 2/4] feat: implement Phase 1 of memory retrieval improvements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 - Foundation complete:

Schema v5 Migration:
- Add entities table for named entity storage
- Add memory_entities junction table for entity-memory mapping
- Add temporal_refs table for date references
- Update migration logic to run on new databases

RRF Fusion Engine (src/git_notes_memory/index/rrf_fusion.py):
- Implement Reciprocal Rank Fusion algorithm (k=60 default)
- Support configurable source weights
- Track source contributions per result
- 28 unit tests for edge cases and score calculations

HybridSearchConfig (src/git_notes_memory/retrieval/config.py):
- Frozen dataclass with all hybrid search settings
- Environment variable loading with sensible defaults
- Integration with RRFConfig for weight extraction
- 23 unit tests for config loading

Retrieval Module Scaffold:
- New retrieval/ module with lazy imports
- Factory function for config singleton

Tests: 141 passing (90 index + 28 RRF + 23 config)

Part of SPEC-2025-12-27-002: Memory Retrieval Performance Improvements
Target: Improve benchmark accuracy from 65% to 90%+

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../PROGRESS.md                               |  24 +-
 src/git_notes_memory/index/rrf_fusion.py      | 245 +++++++++
 src/git_notes_memory/index/schema_manager.py  |  59 ++-
 src/git_notes_memory/retrieval/__init__.py    |  59 +++
 src/git_notes_memory/retrieval/config.py      | 157 ++++++
 tests/index/__init__.py                       |   1 +
 tests/index/test_rrf_fusion.py                | 470 ++++++++++++++++++
 tests/retrieval/__init__.py                   |   1 +
 tests/retrieval/test_config.py                | 237 +++++++++
 tests/test_index.py                           | 145 +++++-
 10 files changed, 1382 insertions(+), 16 deletions(-)
 create mode 100644 src/git_notes_memory/index/rrf_fusion.py
 create mode 100644 src/git_notes_memory/retrieval/__init__.py
 create mode 100644 src/git_notes_memory/retrieval/config.py
 create mode 100644 tests/index/__init__.py
 create mode 100644 tests/index/test_rrf_fusion.py
 create mode 100644 tests/retrieval/__init__.py
 create mode 100644 tests/retrieval/test_config.py

diff --git a/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md b/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
index 08af30cb..24e5fb63 100644
--- a/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
+++ b/docs/spec/active/2025-12-27-memory-retrieval-improvements/PROGRESS.md
@@ -3,7 +3,7 @@ document_type: progress
 project_id: SPEC-2025-12-27-002
 project_name: "Memory Retrieval Performance Improvements"
 started: 2025-12-27T19:00:00Z
-last_updated: 2025-12-27T19:00:00Z
+last_updated: 2025-12-27T20:00:00Z
 ---
 
 # Implementation Progress
@@ -12,22 +12,22 @@ last_updated: 2025-12-27T19:00:00Z
 
 | Metric | Value |
 |--------|-------|
-| **Phase** | 1 of 5 |
-| **Tasks Completed** | 0/21 |
-| **Progress** | 0% |
+| **Phase** | 1 of 5 (completed) |
+| **Tasks Completed** | 4/21 |
+| **Progress** | 19% |
 | **Status** | in-progress |
 
-## Phase 1: Foundation
+## Phase 1: Foundation ✅
 
 | Task | Status | Started | Completed | Notes |
 |------|--------|---------|-----------|-------|
-| 1.1 Schema v5 Migration | pending | - | - | |
-| 1.2 RRF Fusion Engine | pending | - | - | |
-| 1.3 HybridSearchConfig | pending | - | - | |
-| 1.4 Retrieval Module Scaffold | pending | - | - | |
+| 1.1 Schema v5 Migration | done | 2025-12-27 | 2025-12-27 | Added entities, memory_entities, temporal_refs tables |
+| 1.2 RRF Fusion Engine | done | 2025-12-27 | 2025-12-27 | 28 tests passing |
+| 1.3 HybridSearchConfig | done | 2025-12-27 | 2025-12-27 | Env var loading, 23 tests |
+| 1.4 Retrieval Module Scaffold | done | 2025-12-27 | 2025-12-27 | Module structure with lazy imports |
 
-**Phase Status**: pending
-**Phase Progress**: 0/4 tasks
+**Phase Status**: done
+**Phase Progress**: 4/4 tasks
 
 ## Phase 2: Hybrid Search
 
@@ -94,3 +94,5 @@ _None yet._
 
 - Implementation started: 2025-12-27
 - Target: 90%+ accuracy (18/20 questions)
+- Phase 1 completed: Schema v5, RRF fusion, config, retrieval module scaffold
+- 141 tests passing for Phase 1 components
diff --git a/src/git_notes_memory/index/rrf_fusion.py b/src/git_notes_memory/index/rrf_fusion.py
new file mode 100644
index 00000000..a93974e0
--- /dev/null
+++ b/src/git_notes_memory/index/rrf_fusion.py
@@ -0,0 +1,245 @@
+"""Reciprocal Rank Fusion (RRF) engine for combining search rankings.
+
+RET-H-001: RRF provides a robust method for fusing ranked lists from multiple
+search strategies (vector, BM25, entity matching) without requiring score
+normalization.
+
+The RRF formula is:
+    RRF_score(d) = Σ (weight_i / (k + rank_i(d)))
+
+Where:
+- k is a smoothing constant (default 60)
+- weight_i is the weight for ranking source i
+- rank_i(d) is the rank of document d in source i (1-indexed)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["RRFFusionEngine", "RRFConfig", "RankedItem"]
+
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class RRFConfig:
+    """Configuration for RRF fusion.
+
+    Attributes:
+        k: Smoothing constant. Higher values reduce impact of high ranks.
+            Default 60 is standard in literature.
+        weights: Optional weights per source. Keys are source names,
+            values are weight multipliers (default 1.0).
+    """
+
+    k: int = 60
+    weights: tuple[tuple[str, float], ...] = ()
+
+    def get_weight(self, source: str) -> float:
+        """Get weight for a source, defaulting to 1.0."""
+        for name, weight in self.weights:
+            if name == source:
+                return weight
+        return 1.0
+
+
+@dataclass(frozen=True)
+class RankedItem:
+    """A ranked item from a search source.
+
+    Attributes:
+        item_id: Unique identifier for the item.
+        rank: 1-indexed rank in the source's results.
+        score: Optional original score from the source.
+        source: Name of the ranking source.
+        item: The actual item object (e.g., Memory).
+    """
+
+    item_id: str
+    rank: int
+    score: float | None = None
+    source: str = ""
+    item: Any = None
+
+
+@dataclass
+class FusedResult:
+    """Result of RRF fusion for a single item.
+
+    Attributes:
+        item_id: Unique identifier for the item.
+        rrf_score: Combined RRF score.
+        sources: Sources that contributed to this result with their ranks.
+        item: The actual item object (if available from any source).
+    """
+
+    item_id: str
+    rrf_score: float
+    sources: dict[str, int] = field(default_factory=lambda: {})
+    item: Any = None
+
+
+class RRFFusionEngine:
+    """Engine for combining ranked lists using Reciprocal Rank Fusion.
+
+    RRF is parameter-light (just k and optional weights) and works well
+    when combining sources with different score distributions.
+
+    Example:
+        >>> engine = RRFFusionEngine()
+        >>> vector_results = [
+        ...     RankedItem("doc1", rank=1),
+        ...     RankedItem("doc2", rank=2),
+        ... ]
+        >>> bm25_results = [
+        ...     RankedItem("doc2", rank=1),
+        ...     RankedItem("doc1", rank=2),
+        ... ]
+        >>> fused = engine.fuse([
+        ...     ("vector", vector_results),
+        ...     ("bm25", bm25_results),
+        ... ])
+        >>> print(fused[0].item_id)  # doc1 or doc2, depending on weights
+    """
+
+    def __init__(self, config: RRFConfig | None = None) -> None:
+        """Initialize the RRF fusion engine.
+
+        Args:
+            config: Optional RRF configuration. Uses defaults if not provided.
+        """
+        self._config = config or RRFConfig()
+
+    @property
+    def config(self) -> RRFConfig:
+        """Get the current RRF configuration."""
+        return self._config
+
+    def fuse(
+        self,
+        ranked_lists: list[tuple[str, list[RankedItem]]],
+        limit: int | None = None,
+    ) -> list[FusedResult]:
+        """Fuse multiple ranked lists using RRF.
+
+        Args:
+            ranked_lists: List of (source_name, ranked_items) tuples.
+                Each ranked_items list should be ordered by rank (1-indexed).
+            limit: Maximum number of results to return. If None, returns all.
+
+        Returns:
+            List of FusedResult objects, sorted by RRF score descending.
+
+        Raises:
+            ValueError: If any ranks are <= 0.
+        """
+        if not ranked_lists:
+            return []
+
+        # Validate inputs
+        for source_name, items in ranked_lists:
+            for item in items:
+                if item.rank <= 0:
+                    msg = f"Rank must be > 0, got {item.rank} for {item.item_id}"
+                    raise ValueError(msg)
+
+        # Build score accumulator per item
+        scores: dict[str, float] = {}
+        sources: dict[str, dict[str, int]] = {}  # item_id -> {source -> rank}
+        items_by_id: dict[str, Any] = {}  # Store items for later
+
+        k = self._config.k
+
+        for source_name, ranked_items in ranked_lists:
+            weight = self._config.get_weight(source_name)
+
+            for item in ranked_items:
+                item_id = item.item_id
+
+                # Calculate RRF contribution: weight / (k + rank)
+                rrf_contribution = weight / (k + item.rank)
+
+                # Accumulate scores
+                if item_id not in scores:
+                    scores[item_id] = 0.0
+                    sources[item_id] = {}
+                scores[item_id] += rrf_contribution
+                sources[item_id][source_name] = item.rank
+
+                # Store item if available
+                if item.item is not None:
+                    items_by_id[item_id] = item.item
+
+        # Build result list
+        results: list[FusedResult] = []
+        for item_id, rrf_score in scores.items():
+            results.append(
+                FusedResult(
+                    item_id=item_id,
+                    rrf_score=rrf_score,
+                    sources=sources[item_id],
+                    item=items_by_id.get(item_id),
+                )
+            )
+
+        # Sort by RRF score descending
+        results.sort(key=lambda r: r.rrf_score, reverse=True)
+
+        # Apply limit
+        if limit is not None and limit > 0:
+            results = results[:limit]
+
+        return results
+
+    def fuse_with_items(
+        self,
+        ranked_lists: list[tuple[str, list[tuple[T, int, float | None]]]],
+        limit: int | None = None,
+        id_extractor: Any = None,
+    ) -> list[tuple[T, float, dict[str, int]]]:
+        """Fuse ranked lists and return items directly.
+
+        Convenience method when you have items with ranks.
+
+        Args:
+            ranked_lists: List of (source_name, [(item, rank, score), ...]) tuples.
+            limit: Maximum results to return.
+            id_extractor: Function to extract ID from item. Defaults to item.id.
+
+        Returns:
+            List of (item, rrf_score, sources) tuples.
+        """
+
+        def default_id_extractor(x: Any) -> str:
+            return str(x.id) if hasattr(x, "id") else str(x)
+
+        get_id = id_extractor if id_extractor is not None else default_id_extractor
+
+        # Convert to RankedItems
+        converted: list[tuple[str, list[RankedItem]]] = []
+        for source_name, items in ranked_lists:
+            ranked_items: list[RankedItem] = []
+            for item, rank, score in items:
+                item_id = get_id(item)
+                ranked_items.append(
+                    RankedItem(
+                        item_id=item_id,
+                        rank=rank,
+                        score=score,
+                        source=source_name,
+                        item=item,
+                    )
+                )
+            converted.append((source_name, ranked_items))
+
+        # Fuse
+        fused = self.fuse(converted, limit=limit)
+
+        # Convert back to tuple format
+        return [(r.item, r.rrf_score, r.sources) for r in fused if r.item is not None]
diff --git a/src/git_notes_memory/index/schema_manager.py b/src/git_notes_memory/index/schema_manager.py
index 2a95f4b8..635b8427 100644
--- a/src/git_notes_memory/index/schema_manager.py
+++ b/src/git_notes_memory/index/schema_manager.py
@@ -29,7 +29,7 @@
 # =============================================================================
 
 # Schema version for migrations
-SCHEMA_VERSION = 4
+SCHEMA_VERSION = 5
 
 # SQL statements for schema creation
 _CREATE_MEMORIES_TABLE = """
@@ -123,6 +123,59 @@
         END
         """,
     ],
+    5: [
+        # RET-H-001: Entity extraction and indexing for hybrid search
+        # Entities table - stores unique entity references
+        """
+        CREATE TABLE IF NOT EXISTS entities (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            text TEXT NOT NULL,
+            type TEXT NOT NULL,
+            canonical_form TEXT,
+            first_seen TEXT NOT NULL,
+            mention_count INTEGER DEFAULT 1,
+            UNIQUE(text, type)
+        )
+        """,
+        # Index for entity lookups
+        "CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type)",
+        "CREATE INDEX IF NOT EXISTS idx_entities_text ON entities(text)",
+        "CREATE INDEX IF NOT EXISTS idx_entities_canonical ON entities(canonical_form)",
+        # Memory-entity mapping table
+        """
+        CREATE TABLE IF NOT EXISTS memory_entities (
+            memory_id TEXT NOT NULL,
+            entity_id INTEGER NOT NULL,
+            span_start INTEGER,
+            span_end INTEGER,
+            confidence REAL DEFAULT 1.0,
+            PRIMARY KEY (memory_id, entity_id),
+            FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+            FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+        )
+        """,
+        "CREATE INDEX IF NOT EXISTS idx_memory_entities_memory ON memory_entities(memory_id)",
+        "CREATE INDEX IF NOT EXISTS idx_memory_entities_entity ON memory_entities(entity_id)",
+        # RET-H-002: Temporal reference extraction and indexing
+        """
+        CREATE TABLE IF NOT EXISTS temporal_refs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            memory_id TEXT NOT NULL,
+            text TEXT NOT NULL,
+            start_date TEXT,
+            end_date TEXT,
+            granularity TEXT,
+            span_start INTEGER,
+            span_end INTEGER,
+            confidence REAL DEFAULT 1.0,
+            FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+        )
+        """,
+        "CREATE INDEX IF NOT EXISTS idx_temporal_refs_memory ON temporal_refs(memory_id)",
+        "CREATE INDEX IF NOT EXISTS idx_temporal_refs_start ON temporal_refs(start_date)",
+        "CREATE INDEX IF NOT EXISTS idx_temporal_refs_end ON temporal_refs(end_date)",
+        "CREATE INDEX IF NOT EXISTS idx_temporal_refs_dates ON temporal_refs(start_date, end_date)",
+    ],
 }
 
 _CREATE_VEC_TABLE = f"""
@@ -249,7 +302,9 @@ def create_schema(self) -> None:
             cursor.execute(_CREATE_METADATA_TABLE)
 
             # Run migrations if needed
-            if 0 < current_version < SCHEMA_VERSION:
+            # For existing databases (version > 0): migrate from current version
+            # For new databases (version 0): run all migrations to create optional tables
+            if current_version < SCHEMA_VERSION:
                 self.run_migrations(current_version, SCHEMA_VERSION)
 
             # Set schema version
diff --git a/src/git_notes_memory/retrieval/__init__.py b/src/git_notes_memory/retrieval/__init__.py
new file mode 100644
index 00000000..9b0c2fae
--- /dev/null
+++ b/src/git_notes_memory/retrieval/__init__.py
@@ -0,0 +1,59 @@
+"""Memory Retrieval module for hybrid search, entity extraction, and query expansion.
+
+This module provides advanced retrieval capabilities beyond basic vector search:
+
+- **Hybrid Search**: Combines BM25 and vector search using Reciprocal Rank Fusion
+- **Entity Extraction**: Extracts named entities (PERSON, PROJECT, TECHNOLOGY, FILE)
+- **Temporal Extraction**: Parses dates for time-based queries
+- **Query Expansion**: LLM-powered query enhancement
+
+Usage:
+    from git_notes_memory.retrieval import (
+        get_hybrid_search_config,
+        HybridSearchConfig,
+    )
+
+    config = get_hybrid_search_config()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from git_notes_memory.retrieval.config import HybridSearchConfig
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "HybridSearchConfig",
+    "get_hybrid_search_config",
+]
+
+# Lazy-loaded singleton
+_config: HybridSearchConfig | None = None
+
+
+def get_hybrid_search_config() -> HybridSearchConfig:
+    """Get the hybrid search configuration singleton.
+
+    Returns:
+        HybridSearchConfig: Configuration loaded from environment variables.
+    """
+    global _config
+    if _config is None:
+        from git_notes_memory.retrieval.config import HybridSearchConfig
+
+        _config = HybridSearchConfig.from_env()
+    return _config
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for heavy modules."""
+    if name == "HybridSearchConfig":
+        from git_notes_memory.retrieval.config import HybridSearchConfig
+
+        return HybridSearchConfig
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/src/git_notes_memory/retrieval/config.py b/src/git_notes_memory/retrieval/config.py
new file mode 100644
index 00000000..be9757d0
--- /dev/null
+++ b/src/git_notes_memory/retrieval/config.py
@@ -0,0 +1,157 @@
+"""Configuration for hybrid search and retrieval features.
+
+RET-H-003: Configuration dataclass for all retrieval settings,
+loaded from environment variables with sensible defaults.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["HybridSearchConfig", "SearchMode"]
+
+
+SearchMode = Literal["hybrid", "vector", "bm25", "entity"]
+
+
+@dataclass(frozen=True)
+class HybridSearchConfig:
+    """Configuration for hybrid search and retrieval features.
+
+    Attributes:
+        mode: Default search mode. Options: hybrid, vector, bm25, entity.
+        rrf_k: RRF smoothing parameter (default 60).
+        vector_weight: Weight for vector search in RRF (default 1.0).
+        bm25_weight: Weight for BM25 search in RRF (default 1.0).
+        entity_weight: Weight for entity matching in RRF (default 0.8).
+        entity_boost_enabled: Whether to boost results matching query entities.
+        temporal_enabled: Whether to extract and index temporal references.
+        query_expansion_enabled: Whether to use LLM query expansion (opt-in).
+        expand_query_default: Default value for expand_query parameter.
+        parallel_search: Whether to run vector and BM25 searches in parallel.
+        max_results_per_source: Max results from each source before fusion.
+        spacy_model: spaCy model for NER (default: en_core_web_sm).
+    """
+
+    mode: SearchMode = "hybrid"
+    rrf_k: int = 60
+    vector_weight: float = 1.0
+    bm25_weight: float = 1.0
+    entity_weight: float = 0.8
+    entity_boost_enabled: bool = True
+    temporal_enabled: bool = True
+    query_expansion_enabled: bool = True
+    expand_query_default: bool = False  # Opt-in per ADR-007
+    parallel_search: bool = True
+    max_results_per_source: int = 100
+    spacy_model: str = "en_core_web_sm"
+
+    # Environment variable prefix for config
+    _env_prefix: str = field(default="HYBRID_SEARCH_", repr=False, compare=False)
+
+    @classmethod
+    def from_env(cls, prefix: str = "HYBRID_SEARCH_") -> HybridSearchConfig:
+        """Load configuration from environment variables.
+
+        Args:
+            prefix: Environment variable prefix (default: HYBRID_SEARCH_).
+
+        Returns:
+            HybridSearchConfig loaded from environment.
+
+        Environment Variables:
+            HYBRID_SEARCH_MODE: Search mode (hybrid, vector, bm25, entity).
+            HYBRID_SEARCH_RRF_K: RRF k parameter.
+            HYBRID_SEARCH_VECTOR_WEIGHT: Vector search weight.
+            HYBRID_SEARCH_BM25_WEIGHT: BM25 search weight.
+            HYBRID_SEARCH_ENTITY_WEIGHT: Entity matching weight.
+            HYBRID_SEARCH_ENTITY_BOOST_ENABLED: Enable entity boosting.
+            HYBRID_SEARCH_TEMPORAL_ENABLED: Enable temporal extraction.
+            HYBRID_SEARCH_QUERY_EXPANSION_ENABLED: Enable LLM query expansion.
+            HYBRID_SEARCH_EXPAND_QUERY_DEFAULT: Default for expand_query param.
+            HYBRID_SEARCH_PARALLEL: Run searches in parallel.
+            HYBRID_SEARCH_MAX_RESULTS_PER_SOURCE: Max results per source.
+            HYBRID_SEARCH_SPACY_MODEL: spaCy model name.
+        """
+
+        def get_str(key: str, default: str) -> str:
+            return os.environ.get(f"{prefix}{key}", default)
+
+        def get_int(key: str, default: int) -> int:
+            value = os.environ.get(f"{prefix}{key}")
+            if value is None:
+                return default
+            try:
+                return int(value)
+            except ValueError:
+                logger.warning(
+                    "Invalid int value for %s%s: %s, using default %d",
+                    prefix,
+                    key,
+                    value,
+                    default,
+                )
+                return default
+
+        def get_float(key: str, default: float) -> float:
+            value = os.environ.get(f"{prefix}{key}")
+            if value is None:
+                return default
+            try:
+                return float(value)
+            except ValueError:
+                logger.warning(
+                    "Invalid float value for %s%s: %s, using default %f",
+                    prefix,
+                    key,
+                    value,
+                    default,
+                )
+                return default
+
+        def get_bool(key: str, default: bool) -> bool:
+            value = os.environ.get(f"{prefix}{key}")
+            if value is None:
+                return default
+            return value.lower() in ("true", "1", "yes", "on")
+
+        # Validate mode
+        mode_value = get_str("MODE", "hybrid")
+        if mode_value not in ("hybrid", "vector", "bm25", "entity"):
+            logger.warning(
+                "Invalid search mode: %s, using 'hybrid'",
+                mode_value,
+            )
+            mode_value = "hybrid"
+
+        return cls(
+            mode=mode_value,
+            rrf_k=get_int("RRF_K", 60),
+            vector_weight=get_float("VECTOR_WEIGHT", 1.0),
+            bm25_weight=get_float("BM25_WEIGHT", 1.0),
+            entity_weight=get_float("ENTITY_WEIGHT", 0.8),
+            entity_boost_enabled=get_bool("ENTITY_BOOST_ENABLED", True),
+            temporal_enabled=get_bool("TEMPORAL_ENABLED", True),
+            query_expansion_enabled=get_bool("QUERY_EXPANSION_ENABLED", True),
+            expand_query_default=get_bool("EXPAND_QUERY_DEFAULT", False),
+            parallel_search=get_bool("PARALLEL", True),
+            max_results_per_source=get_int("MAX_RESULTS_PER_SOURCE", 100),
+            spacy_model=get_str("SPACY_MODEL", "en_core_web_sm"),
+        )
+
+    def get_rrf_weights(self) -> tuple[tuple[str, float], ...]:
+        """Get weights as tuples for RRFConfig.
+
+        Returns:
+            Tuple of (source_name, weight) tuples.
+        """
+        return (
+            ("vector", self.vector_weight),
+            ("bm25", self.bm25_weight),
+            ("entity", self.entity_weight),
+        )
diff --git a/tests/index/__init__.py b/tests/index/__init__.py
new file mode 100644
index 00000000..24171d02
--- /dev/null
+++ b/tests/index/__init__.py
@@ -0,0 +1 @@
+"""Index tests package."""
diff --git a/tests/index/test_rrf_fusion.py b/tests/index/test_rrf_fusion.py
new file mode 100644
index 00000000..63599ffd
--- /dev/null
+++ b/tests/index/test_rrf_fusion.py
@@ -0,0 +1,470 @@
+"""Tests for the RRF Fusion Engine.
+
+Tests cover:
+- Basic RRF fusion algorithm
+- Weighted sources
+- Edge cases (empty lists, single source, ties)
+- Configuration options
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+
+from git_notes_memory.index.rrf_fusion import (
+    FusedResult,
+    RankedItem,
+    RRFConfig,
+    RRFFusionEngine,
+)
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def engine() -> RRFFusionEngine:
+    """Create a default RRF fusion engine."""
+    return RRFFusionEngine()
+
+
+@pytest.fixture
+def weighted_engine() -> RRFFusionEngine:
+    """Create an RRF engine with custom weights."""
+    config = RRFConfig(
+        k=60,
+        weights=(("vector", 1.5), ("bm25", 1.0)),
+    )
+    return RRFFusionEngine(config)
+
+
+@dataclass
+class MockItem:
+    """Mock item for testing."""
+
+    id: str
+    name: str
+
+
+# =============================================================================
+# Test: RRFConfig
+# =============================================================================
+
+
+class TestRRFConfig:
+    """Test RRFConfig dataclass."""
+
+    def test_default_config(self) -> None:
+        """Test default configuration values."""
+        config = RRFConfig()
+        assert config.k == 60
+        assert config.weights == ()
+
+    def test_custom_k(self) -> None:
+        """Test custom k parameter."""
+        config = RRFConfig(k=100)
+        assert config.k == 100
+
+    def test_custom_weights(self) -> None:
+        """Test custom weights."""
+        config = RRFConfig(weights=(("vector", 1.5), ("bm25", 0.8)))
+        assert config.get_weight("vector") == 1.5
+        assert config.get_weight("bm25") == 0.8
+
+    def test_default_weight_for_unknown_source(self) -> None:
+        """Test default weight of 1.0 for unknown sources."""
+        config = RRFConfig(weights=(("vector", 1.5),))
+        assert config.get_weight("unknown") == 1.0
+
+
+# =============================================================================
+# Test: RankedItem
+# =============================================================================
+
+
+class TestRankedItem:
+    """Test RankedItem dataclass."""
+
+    def test_basic_item(self) -> None:
+        """Test basic RankedItem creation."""
+        item = RankedItem(item_id="doc1", rank=1)
+        assert item.item_id == "doc1"
+        assert item.rank == 1
+        assert item.score is None
+        assert item.source == ""
+        assert item.item is None
+
+    def test_full_item(self) -> None:
+        """Test RankedItem with all fields."""
+        mock = MockItem(id="doc1", name="Test")
+        item = RankedItem(
+            item_id="doc1",
+            rank=1,
+            score=0.95,
+            source="vector",
+            item=mock,
+        )
+        assert item.score == 0.95
+        assert item.source == "vector"
+        assert item.item == mock
+
+
+# =============================================================================
+# Test: Basic Fusion
+# =============================================================================
+
+
+class TestBasicFusion:
+    """Test basic RRF fusion operations."""
+
+    def test_empty_input(self, engine: RRFFusionEngine) -> None:
+        """Test fusion with empty input."""
+        result = engine.fuse([])
+        assert result == []
+
+    def test_single_source(self, engine: RRFFusionEngine) -> None:
+        """Test fusion with a single source."""
+        items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+            RankedItem("doc3", rank=3),
+        ]
+        result = engine.fuse([("vector", items)])
+
+        assert len(result) == 3
+        # First item should have highest score
+        assert result[0].item_id == "doc1"
+        assert result[1].item_id == "doc2"
+        assert result[2].item_id == "doc3"
+
+    def test_two_sources_same_order(self, engine: RRFFusionEngine) -> None:
+        """Test fusion with two sources agreeing on order."""
+        vector_items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        bm25_items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert len(result) == 2
+        # doc1 ranked first by both, should be first
+        assert result[0].item_id == "doc1"
+        assert result[1].item_id == "doc2"
+
+    def test_two_sources_different_order(self, engine: RRFFusionEngine) -> None:
+        """Test fusion with two sources with different orders."""
+        vector_items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        bm25_items = [
+            RankedItem("doc2", rank=1),
+            RankedItem("doc1", rank=2),
+        ]
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert len(result) == 2
+        # Both docs have same cumulative score (1/61 + 1/62)
+        # They should both appear, order may vary due to dict ordering
+        item_ids = {r.item_id for r in result}
+        assert item_ids == {"doc1", "doc2"}
+
+    def test_item_only_in_one_source(self, engine: RRFFusionEngine) -> None:
+        """Test fusion when an item appears in only one source."""
+        vector_items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        bm25_items = [
+            RankedItem("doc3", rank=1),  # Only in BM25
+            RankedItem("doc1", rank=2),
+        ]
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert len(result) == 3
+        item_ids = {r.item_id for r in result}
+        assert item_ids == {"doc1", "doc2", "doc3"}
+
+        # doc1 appears in both, should have higher score than doc2 or doc3 alone
+        doc1_result = next(r for r in result if r.item_id == "doc1")
+        doc2_result = next(r for r in result if r.item_id == "doc2")
+        doc3_result = next(r for r in result if r.item_id == "doc3")
+
+        # doc1: 1/61 + 1/62 > doc3: 1/61 (alone) or doc2: 1/62 (alone)
+        assert doc1_result.rrf_score > doc2_result.rrf_score
+        assert doc1_result.rrf_score > doc3_result.rrf_score
+
+
+class TestFusionWithLimit:
+    """Test RRF fusion with result limits."""
+
+    def test_limit_results(self, engine: RRFFusionEngine) -> None:
+        """Test limiting number of results."""
+        items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+            RankedItem("doc3", rank=3),
+        ]
+        result = engine.fuse([("vector", items)], limit=2)
+
+        assert len(result) == 2
+        assert result[0].item_id == "doc1"
+        assert result[1].item_id == "doc2"
+
+    def test_limit_greater_than_results(self, engine: RRFFusionEngine) -> None:
+        """Test limit greater than available results."""
+        items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        result = engine.fuse([("vector", items)], limit=10)
+
+        assert len(result) == 2
+
+
+# =============================================================================
+# Test: Weighted Fusion
+# =============================================================================
+
+
+class TestWeightedFusion:
+    """Test RRF fusion with weighted sources."""
+
+    def test_weighted_sources(self, weighted_engine: RRFFusionEngine) -> None:
+        """Test that weights affect ranking."""
+        # Vector ranked first, BM25 ranked second
+        vector_items = [
+            RankedItem("doc1", rank=1),
+            RankedItem("doc2", rank=2),
+        ]
+        bm25_items = [
+            RankedItem("doc2", rank=1),
+            RankedItem("doc1", rank=2),
+        ]
+        result = weighted_engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        # doc1: vector weight 1.5/61 + bm25 weight 1.0/62
+        # doc2: vector weight 1.5/62 + bm25 weight 1.0/61
+        # 1.5/61 + 1.0/62 > 1.5/62 + 1.0/61
+        # doc1 should be ranked higher due to higher weight on vector
+        assert result[0].item_id == "doc1"
+
+
+# =============================================================================
+# Test: Score Calculations
+# =============================================================================
+
+
+class TestScoreCalculations:
+    """Test RRF score calculations."""
+
+    def test_score_formula(self) -> None:
+        """Test RRF score formula correctness."""
+        # k=60, weight=1.0, rank=1 -> 1/(60+1) = 1/61
+        config = RRFConfig(k=60)
+        engine = RRFFusionEngine(config)
+
+        items = [RankedItem("doc1", rank=1)]
+        result = engine.fuse([("test", items)])
+
+        expected_score = 1.0 / (60 + 1)
+        assert abs(result[0].rrf_score - expected_score) < 0.0001
+
+    def test_score_accumulation(self) -> None:
+        """Test that scores accumulate across sources."""
+        engine = RRFFusionEngine(RRFConfig(k=60))
+
+        vector_items = [RankedItem("doc1", rank=1)]
+        bm25_items = [RankedItem("doc1", rank=1)]
+
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        # doc1: 1/61 + 1/61 = 2/61
+        expected_score = 2.0 / 61
+        assert abs(result[0].rrf_score - expected_score) < 0.0001
+
+    def test_custom_k_affects_score(self) -> None:
+        """Test that k parameter affects scores."""
+        engine_k60 = RRFFusionEngine(RRFConfig(k=60))
+        engine_k100 = RRFFusionEngine(RRFConfig(k=100))
+
+        items = [RankedItem("doc1", rank=1)]
+
+        result_k60 = engine_k60.fuse([("test", items)])
+        result_k100 = engine_k100.fuse([("test", items)])
+
+        # Higher k means lower score for same rank
+        assert result_k60[0].rrf_score > result_k100[0].rrf_score
+
+
+# =============================================================================
+# Test: Source Tracking
+# =============================================================================
+
+
+class TestSourceTracking:
+    """Test that sources are properly tracked in results."""
+
+    def test_sources_tracked(self, engine: RRFFusionEngine) -> None:
+        """Test that source contributions are recorded."""
+        vector_items = [RankedItem("doc1", rank=1)]
+        bm25_items = [RankedItem("doc1", rank=3)]
+
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert result[0].sources == {"vector": 1, "bm25": 3}
+
+    def test_single_source_tracked(self, engine: RRFFusionEngine) -> None:
+        """Test source tracking for item in single source."""
+        vector_items = [RankedItem("doc1", rank=1)]
+        bm25_items = [RankedItem("doc2", rank=1)]
+
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        doc1_result = next(r for r in result if r.item_id == "doc1")
+        doc2_result = next(r for r in result if r.item_id == "doc2")
+
+        assert doc1_result.sources == {"vector": 1}
+        assert doc2_result.sources == {"bm25": 1}
+
+
+# =============================================================================
+# Test: Item Preservation
+# =============================================================================
+
+
+class TestItemPreservation:
+    """Test that item objects are preserved through fusion."""
+
+    def test_item_preserved(self, engine: RRFFusionEngine) -> None:
+        """Test that item objects are included in results."""
+        mock = MockItem(id="doc1", name="Test Document")
+        items = [RankedItem("doc1", rank=1, item=mock)]
+
+        result = engine.fuse([("test", items)])
+
+        assert result[0].item == mock
+        assert result[0].item.name == "Test Document"
+
+    def test_item_from_any_source(self, engine: RRFFusionEngine) -> None:
+        """Test that item is taken from whichever source has it."""
+        mock = MockItem(id="doc1", name="From Vector")
+        vector_items = [RankedItem("doc1", rank=1, item=mock)]
+        bm25_items = [RankedItem("doc1", rank=2)]  # No item
+
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert result[0].item == mock
+
+
+# =============================================================================
+# Test: Edge Cases
+# =============================================================================
+
+
+class TestEdgeCases:
+    """Test edge cases and error handling."""
+
+    def test_invalid_rank_zero(self, engine: RRFFusionEngine) -> None:
+        """Test that rank 0 raises ValueError."""
+        items = [RankedItem("doc1", rank=0)]
+
+        with pytest.raises(ValueError, match="Rank must be > 0"):
+            engine.fuse([("test", items)])
+
+    def test_invalid_rank_negative(self, engine: RRFFusionEngine) -> None:
+        """Test that negative rank raises ValueError."""
+        items = [RankedItem("doc1", rank=-1)]
+
+        with pytest.raises(ValueError, match="Rank must be > 0"):
+            engine.fuse([("test", items)])
+
+    def test_many_sources(self, engine: RRFFusionEngine) -> None:
+        """Test fusion with many sources."""
+        sources = []
+        for i in range(10):
+            sources.append((f"source{i}", [RankedItem("doc1", rank=1)]))
+
+        result = engine.fuse(sources)
+
+        # Should have 10x the single-source score
+        expected_score = 10.0 / 61
+        assert abs(result[0].rrf_score - expected_score) < 0.0001
+
+    def test_empty_source_list(self, engine: RRFFusionEngine) -> None:
+        """Test fusion when a source has no items."""
+        vector_items = [RankedItem("doc1", rank=1)]
+        bm25_items: list[RankedItem] = []  # Empty
+
+        result = engine.fuse([("vector", vector_items), ("bm25", bm25_items)])
+
+        assert len(result) == 1
+        assert result[0].item_id == "doc1"
+
+    def test_large_ranks(self, engine: RRFFusionEngine) -> None:
+        """Test with large rank values."""
+        items = [RankedItem("doc1", rank=1000)]
+
+        result = engine.fuse([("test", items)])
+
+        # Score should be 1/(60+1000) = 1/1060
+        expected_score = 1.0 / 1060
+        assert abs(result[0].rrf_score - expected_score) < 0.0001
+
+
+# =============================================================================
+# Test: Convenience Method
+# =============================================================================
+
+
+class TestFuseWithItems:
+    """Test the fuse_with_items convenience method."""
+
+    def test_basic_usage(self, engine: RRFFusionEngine) -> None:
+        """Test basic fuse_with_items usage."""
+        item1 = MockItem(id="doc1", name="Doc 1")
+        item2 = MockItem(id="doc2", name="Doc 2")
+
+        vector_list = [(item1, 1, 0.9), (item2, 2, 0.8)]
+        bm25_list = [(item2, 1, 10.0), (item1, 2, 8.0)]
+
+        result = engine.fuse_with_items(
+            [("vector", vector_list), ("bm25", bm25_list)],
+        )
+
+        assert len(result) == 2
+        # Each result is (item, rrf_score, sources)
+        assert all(isinstance(r[0], MockItem) for r in result)
+        assert all(isinstance(r[1], float) for r in result)
+        assert all(isinstance(r[2], dict) for r in result)
+
+    def test_custom_id_extractor(self, engine: RRFFusionEngine) -> None:
+        """Test with custom ID extractor."""
+
+        @dataclass
+        class CustomItem:
+            custom_id: str
+            value: int
+
+        item1 = CustomItem(custom_id="x1", value=100)
+        item2 = CustomItem(custom_id="x2", value=200)
+
+        vector_list = [(item1, 1, 0.9), (item2, 2, 0.8)]
+
+        def custom_extractor(item: CustomItem) -> str:
+            return item.custom_id
+
+        result = engine.fuse_with_items(
+            [("vector", vector_list)],
+            id_extractor=custom_extractor,
+        )
+
+        assert len(result) == 2
+        assert result[0][0].custom_id == "x1"
diff --git a/tests/retrieval/__init__.py b/tests/retrieval/__init__.py
new file mode 100644
index 00000000..06987374
--- /dev/null
+++ b/tests/retrieval/__init__.py
@@ -0,0 +1 @@
+"""Retrieval tests package."""
diff --git a/tests/retrieval/test_config.py b/tests/retrieval/test_config.py
new file mode 100644
index 00000000..38737740
--- /dev/null
+++ b/tests/retrieval/test_config.py
@@ -0,0 +1,237 @@
+"""Tests for HybridSearchConfig.
+
+Tests cover:
+- Default configuration values
+- Environment variable loading
+- Invalid value handling
+- RRF weights extraction
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from git_notes_memory.retrieval.config import HybridSearchConfig
+
+
+# =============================================================================
+# Test: Default Configuration
+# =============================================================================
+
+
+class TestDefaultConfig:
+    """Test default configuration values."""
+
+    def test_default_mode(self) -> None:
+        """Test default search mode is hybrid."""
+        config = HybridSearchConfig()
+        assert config.mode == "hybrid"
+
+    def test_default_rrf_k(self) -> None:
+        """Test default RRF k is 60."""
+        config = HybridSearchConfig()
+        assert config.rrf_k == 60
+
+    def test_default_weights(self) -> None:
+        """Test default weights."""
+        config = HybridSearchConfig()
+        assert config.vector_weight == 1.0
+        assert config.bm25_weight == 1.0
+        assert config.entity_weight == 0.8
+
+    def test_default_features_enabled(self) -> None:
+        """Test default feature flags."""
+        config = HybridSearchConfig()
+        assert config.entity_boost_enabled is True
+        assert config.temporal_enabled is True
+        assert config.query_expansion_enabled is True
+        assert config.expand_query_default is False  # Opt-in per ADR-007
+        assert config.parallel_search is True
+
+    def test_default_max_results(self) -> None:
+        """Test default max results per source."""
+        config = HybridSearchConfig()
+        assert config.max_results_per_source == 100
+
+    def test_default_spacy_model(self) -> None:
+        """Test default spaCy model."""
+        config = HybridSearchConfig()
+        assert config.spacy_model == "en_core_web_sm"
+
+
+# =============================================================================
+# Test: Custom Configuration
+# =============================================================================
+
+
+class TestCustomConfig:
+    """Test custom configuration."""
+
+    def test_custom_mode(self) -> None:
+        """Test custom search mode."""
+        config = HybridSearchConfig(mode="vector")
+        assert config.mode == "vector"
+
+    def test_custom_weights(self) -> None:
+        """Test custom weights."""
+        config = HybridSearchConfig(
+            vector_weight=1.5,
+            bm25_weight=0.8,
+            entity_weight=1.2,
+        )
+        assert config.vector_weight == 1.5
+        assert config.bm25_weight == 0.8
+        assert config.entity_weight == 1.2
+
+    def test_frozen_config(self) -> None:
+        """Test config is immutable."""
+        config = HybridSearchConfig()
+        with pytest.raises(AttributeError):
+            config.mode = "vector"  # type: ignore[misc]  # noqa: E501
+
+
+# =============================================================================
+# Test: Environment Variable Loading
+# =============================================================================
+
+
+class TestEnvLoading:
+    """Test loading config from environment variables."""
+
+    def test_load_mode_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading mode from env."""
+        monkeypatch.setenv("HYBRID_SEARCH_MODE", "bm25")
+        config = HybridSearchConfig.from_env()
+        assert config.mode == "bm25"
+
+    def test_load_rrf_k_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading RRF k from env."""
+        monkeypatch.setenv("HYBRID_SEARCH_RRF_K", "100")
+        config = HybridSearchConfig.from_env()
+        assert config.rrf_k == 100
+
+    def test_load_weights_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading weights from env."""
+        monkeypatch.setenv("HYBRID_SEARCH_VECTOR_WEIGHT", "1.5")
+        monkeypatch.setenv("HYBRID_SEARCH_BM25_WEIGHT", "0.8")
+        monkeypatch.setenv("HYBRID_SEARCH_ENTITY_WEIGHT", "1.2")
+        config = HybridSearchConfig.from_env()
+        assert config.vector_weight == 1.5
+        assert config.bm25_weight == 0.8
+        assert config.entity_weight == 1.2
+
+    def test_load_bool_true_variants(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading boolean true variants."""
+        for val in ("true", "True", "TRUE", "1", "yes", "on"):
+            monkeypatch.setenv("HYBRID_SEARCH_ENTITY_BOOST_ENABLED", val)
+            config = HybridSearchConfig.from_env()
+            assert config.entity_boost_enabled is True, f"Failed for value: {val}"
+
+    def test_load_bool_false_variants(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading boolean false variants."""
+        for val in ("false", "False", "FALSE", "0", "no", "off"):
+            monkeypatch.setenv("HYBRID_SEARCH_ENTITY_BOOST_ENABLED", val)
+            config = HybridSearchConfig.from_env()
+            assert config.entity_boost_enabled is False, f"Failed for value: {val}"
+
+    def test_load_parallel_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading parallel setting from env."""
+        monkeypatch.setenv("HYBRID_SEARCH_PARALLEL", "false")
+        config = HybridSearchConfig.from_env()
+        assert config.parallel_search is False
+
+    def test_load_spacy_model_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading spaCy model from env."""
+        monkeypatch.setenv("HYBRID_SEARCH_SPACY_MODEL", "en_core_web_lg")
+        config = HybridSearchConfig.from_env()
+        assert config.spacy_model == "en_core_web_lg"
+
+    def test_custom_prefix(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading with custom prefix."""
+        monkeypatch.setenv("CUSTOM_MODE", "vector")
+        config = HybridSearchConfig.from_env(prefix="CUSTOM_")
+        assert config.mode == "vector"
+
+
+# =============================================================================
+# Test: Invalid Values
+# =============================================================================
+
+
+class TestInvalidValues:
+    """Test handling of invalid environment values."""
+
+    def test_invalid_int_uses_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test invalid int falls back to default."""
+        monkeypatch.setenv("HYBRID_SEARCH_RRF_K", "not_a_number")
+        config = HybridSearchConfig.from_env()
+        assert config.rrf_k == 60  # Default
+
+    def test_invalid_float_uses_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test invalid float falls back to default."""
+        monkeypatch.setenv("HYBRID_SEARCH_VECTOR_WEIGHT", "not_a_number")
+        config = HybridSearchConfig.from_env()
+        assert config.vector_weight == 1.0  # Default
+
+    def test_invalid_mode_uses_hybrid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test invalid mode falls back to hybrid."""
+        monkeypatch.setenv("HYBRID_SEARCH_MODE", "invalid_mode")
+        config = HybridSearchConfig.from_env()
+        assert config.mode == "hybrid"
+
+
+# =============================================================================
+# Test: RRF Weights Extraction
+# =============================================================================
+
+
+class TestRRFWeights:
+    """Test RRF weights extraction."""
+
+    def test_get_rrf_weights_default(self) -> None:
+        """Test default RRF weights extraction."""
+        config = HybridSearchConfig()
+        weights = config.get_rrf_weights()
+
+        assert weights == (
+            ("vector", 1.0),
+            ("bm25", 1.0),
+            ("entity", 0.8),
+        )
+
+    def test_get_rrf_weights_custom(self) -> None:
+        """Test custom RRF weights extraction."""
+        config = HybridSearchConfig(
+            vector_weight=1.5,
+            bm25_weight=0.5,
+            entity_weight=2.0,
+        )
+        weights = config.get_rrf_weights()
+
+        assert weights == (
+            ("vector", 1.5),
+            ("bm25", 0.5),
+            ("entity", 2.0),
+        )
+
+
+# =============================================================================
+# Test: Integration with RRFConfig
+# =============================================================================
+
+
+class TestRRFIntegration:
+    """Test integration with RRFConfig."""
+
+    def test_weights_compatible_with_rrf_config(self) -> None:
+        """Test that weights work with RRFConfig."""
+        from git_notes_memory.index.rrf_fusion import RRFConfig
+
+        config = HybridSearchConfig()
+        weights = config.get_rrf_weights()
+
+        rrf_config = RRFConfig(k=config.rrf_k, weights=weights)
+
+        assert rrf_config.get_weight("vector") == 1.0
+        assert rrf_config.get_weight("bm25") == 1.0
+        assert rrf_config.get_weight("entity") == 0.8
diff --git a/tests/test_index.py b/tests/test_index.py
index d55ea9d6..6de111ae 100644
--- a/tests/test_index.py
+++ b/tests/test_index.py
@@ -153,7 +153,7 @@ def test_initialize_sets_schema_version(self, db_path: Path) -> None:
         cursor.execute("SELECT value FROM metadata WHERE key = 'schema_version'")
         row = cursor.fetchone()
         assert row is not None
-        assert row[0] == "4"  # Schema v4 adds FTS5 full-text search
+        assert row[0] == "5"  # Schema v5 adds entity/temporal tables
 
         service.close()
 
@@ -248,10 +248,10 @@ def test_migration_from_v2_to_v3_adds_domain_column(self, db_path: Path) -> None
         columns = {row["name"] for row in cursor.fetchall()}
         assert "domain" in columns
 
-        # Check schema version updated to 4 (latest)
+        # Check schema version updated to 5 (latest)
         cursor.execute("SELECT value FROM metadata WHERE key = 'schema_version'")
         row = cursor.fetchone()
-        assert row[0] == "4"
+        assert row[0] == "5"
 
         # Check index exists
         cursor.execute(
@@ -273,6 +273,145 @@ def test_new_database_has_domain_column(self, db_path: Path) -> None:
 
         service.close()
 
+    def test_new_database_has_entity_tables(self, db_path: Path) -> None:
+        """Test a fresh database has entity tables from schema v5."""
+        service = IndexService(db_path)
+        service.initialize()
+
+        cursor = service._conn.cursor()
+
+        # Check entities table exists
+        cursor.execute("PRAGMA table_info(entities)")
+        columns = {row["name"] for row in cursor.fetchall()}
+        assert "id" in columns
+        assert "text" in columns
+        assert "type" in columns
+        assert "canonical_form" in columns
+        assert "first_seen" in columns
+        assert "mention_count" in columns
+
+        # Check memory_entities table exists
+        cursor.execute("PRAGMA table_info(memory_entities)")
+        columns = {row["name"] for row in cursor.fetchall()}
+        assert "memory_id" in columns
+        assert "entity_id" in columns
+        assert "span_start" in columns
+        assert "span_end" in columns
+        assert "confidence" in columns
+
+        service.close()
+
+    def test_new_database_has_temporal_refs_table(self, db_path: Path) -> None:
+        """Test a fresh database has temporal_refs table from schema v5."""
+        service = IndexService(db_path)
+        service.initialize()
+
+        cursor = service._conn.cursor()
+
+        # Check temporal_refs table exists
+        cursor.execute("PRAGMA table_info(temporal_refs)")
+        columns = {row["name"] for row in cursor.fetchall()}
+        assert "id" in columns
+        assert "memory_id" in columns
+        assert "text" in columns
+        assert "start_date" in columns
+        assert "end_date" in columns
+        assert "granularity" in columns
+        assert "span_start" in columns
+        assert "span_end" in columns
+        assert "confidence" in columns
+
+        service.close()
+
+    def test_migration_from_v4_to_v5_adds_entity_tables(self, db_path: Path) -> None:
+        """Test migration from v4 to v5 adds entity and temporal tables."""
+        import sqlite3
+
+        import sqlite_vec
+
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+        conn.enable_load_extension(True)
+        sqlite_vec.load(conn)
+        conn.enable_load_extension(False)
+
+        # Create v4 schema (with FTS5 but without entity tables)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id TEXT PRIMARY KEY,
+                commit_sha TEXT NOT NULL,
+                namespace TEXT NOT NULL,
+                summary TEXT NOT NULL,
+                content TEXT NOT NULL,
+                timestamp TEXT NOT NULL,
+                domain TEXT DEFAULT 'project',
+                repo_path TEXT,
+                spec TEXT,
+                phase TEXT,
+                tags TEXT,
+                status TEXT DEFAULT 'active',
+                relates_to TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            )
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS metadata (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL
+            )
+        """)
+        conn.execute("INSERT INTO metadata (key, value) VALUES ('schema_version', '4')")
+        conn.execute("""
+            CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(
+                id TEXT PRIMARY KEY,
+                embedding FLOAT[384]
+            )
+        """)
+        # Add FTS5 table to simulate v4
+        conn.execute("""
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+                id UNINDEXED,
+                summary,
+                content,
+                content='memories',
+                content_rowid='rowid'
+            )
+        """)
+        conn.commit()
+        conn.close()
+
+        # Now initialize IndexService - it should run migration
+        service = IndexService(db_path)
+        service.initialize()
+
+        cursor = service._conn.cursor()
+
+        # Check entities table was created
+        cursor.execute("PRAGMA table_info(entities)")
+        entity_columns = {row["name"] for row in cursor.fetchall()}
+        assert "text" in entity_columns
+        assert "type" in entity_columns
+
+        # Check memory_entities table was created
+        cursor.execute("PRAGMA table_info(memory_entities)")
+        me_columns = {row["name"] for row in cursor.fetchall()}
+        assert "memory_id" in me_columns
+        assert "entity_id" in me_columns
+
+        # Check temporal_refs table was created
+        cursor.execute("PRAGMA table_info(temporal_refs)")
+        tr_columns = {row["name"] for row in cursor.fetchall()}
+        assert "memory_id" in tr_columns
+        assert "start_date" in tr_columns
+
+        # Check schema version updated to 5
+        cursor.execute("SELECT value FROM metadata WHERE key = 'schema_version'")
+        row = cursor.fetchone()
+        assert row[0] == "5"
+
+        service.close()
+
 
 class TestInitializationErrors:
     """Test error handling during initialization."""

From 20a2fb9015d1be45dcfb5c189d5b82f4466796d3 Mon Sep 17 00:00:00 2001
From: Robert Allen <zircote@gmail.com>
Date: Sat, 27 Dec 2025 17:38:18 -0500
Subject: [PATCH 3/4] fix: resolve lint and type errors in Phase 1 code
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix B007 in rrf_fusion.py: rename unused loop variable to _source_name
- Fix mypy type narrowing in config.py: explicit SearchMode cast

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/git_notes_memory/index/rrf_fusion.py | 12 +++++++-----
 src/git_notes_memory/retrieval/config.py | 10 ++++++++--
 tests/index/test_rrf_fusion.py           |  2 --
 tests/retrieval/test_config.py           |  1 -
 4 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/git_notes_memory/index/rrf_fusion.py b/src/git_notes_memory/index/rrf_fusion.py
index a93974e0..7a5a54c2 100644
--- a/src/git_notes_memory/index/rrf_fusion.py
+++ b/src/git_notes_memory/index/rrf_fusion.py
@@ -101,10 +101,12 @@ class RRFFusionEngine:
         ...     RankedItem("doc2", rank=1),
         ...     RankedItem("doc1", rank=2),
         ... ]
-        >>> fused = engine.fuse([
-        ...     ("vector", vector_results),
-        ...     ("bm25", bm25_results),
-        ... ])
+        >>> fused = engine.fuse(
+        ...     [
+        ...         ("vector", vector_results),
+        ...         ("bm25", bm25_results),
+        ...     ]
+        ... )
         >>> print(fused[0].item_id)  # doc1 or doc2, depending on weights
     """
 
@@ -143,7 +145,7 @@ def fuse(
             return []
 
         # Validate inputs
-        for source_name, items in ranked_lists:
+        for _source_name, items in ranked_lists:
             for item in items:
                 if item.rank <= 0:
                     msg = f"Rank must be > 0, got {item.rank} for {item.item_id}"
diff --git a/src/git_notes_memory/retrieval/config.py b/src/git_notes_memory/retrieval/config.py
index be9757d0..d74f9a33 100644
--- a/src/git_notes_memory/retrieval/config.py
+++ b/src/git_notes_memory/retrieval/config.py
@@ -122,15 +122,21 @@ def get_bool(key: str, default: bool) -> bool:
 
         # Validate mode
         mode_value = get_str("MODE", "hybrid")
-        if mode_value not in ("hybrid", "vector", "bm25", "entity"):
+        valid_modes = ("hybrid", "vector", "bm25", "entity")
+        if mode_value not in valid_modes:
             logger.warning(
                 "Invalid search mode: %s, using 'hybrid'",
                 mode_value,
             )
             mode_value = "hybrid"
 
+        # Cast to SearchMode type
+        validated_mode: SearchMode = (
+            mode_value if mode_value in valid_modes else "hybrid"
+        )
+
         return cls(
-            mode=mode_value,
+            mode=validated_mode,
             rrf_k=get_int("RRF_K", 60),
             vector_weight=get_float("VECTOR_WEIGHT", 1.0),
             bm25_weight=get_float("BM25_WEIGHT", 1.0),
diff --git a/tests/index/test_rrf_fusion.py b/tests/index/test_rrf_fusion.py
index 63599ffd..8d9f1c85 100644
--- a/tests/index/test_rrf_fusion.py
+++ b/tests/index/test_rrf_fusion.py
@@ -14,13 +14,11 @@
 import pytest
 
 from git_notes_memory.index.rrf_fusion import (
-    FusedResult,
     RankedItem,
     RRFConfig,
     RRFFusionEngine,
 )
 
-
 # =============================================================================
 # Fixtures
 # =============================================================================
diff --git a/tests/retrieval/test_config.py b/tests/retrieval/test_config.py
index 38737740..2a795097 100644
--- a/tests/retrieval/test_config.py
+++ b/tests/retrieval/test_config.py
@@ -13,7 +13,6 @@
 
 from git_notes_memory.retrieval.config import HybridSearchConfig
 
-
 # =============================================================================
 # Test: Default Configuration
 # =============================================================================

From 28edcb1ea3d0850aa796d5757d9d166c148953fa Mon Sep 17 00:00:00 2001
From: Robert Allen <zircote@gmail.com>
Date: Sat, 27 Dec 2025 17:59:18 -0500
Subject: [PATCH 4/4] feat(retrieval): implement Phase 2 hybrid search with RRF
 fusion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 implementation of memory retrieval improvements:

- Task 2.1: HybridSearchEngine with parallel vector + BM25 search
  - Reciprocal Rank Fusion combining multiple strategies
  - Mode selection: hybrid, vector, bm25
  - Configurable weights and RRF k parameter
  - Observability integration with metrics and tracing

- Task 2.2: Extend SearchEngine with ranking methods
  - search_vector_ranked() returns (memory, rank, distance)
  - search_text_ranked() returns (memory, rank, bm25_score)
  - Ranks are 1-indexed for RRF compatibility

- Task 2.3: Extend RecallService with hybrid parameters
  - search_hybrid() method for RRF-fused search
  - Lazy-initialized HybridSearchEngine
  - Thread-safe initialization with double-checked locking

Tests: 74 passing (21 hybrid, 28 RRF, 25 config)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/git_notes_memory/index/__init__.py      |   7 +
 src/git_notes_memory/index/hybrid_search.py | 340 +++++++++++++++
 src/git_notes_memory/index/search_engine.py | 114 +++++
 src/git_notes_memory/recall.py              | 142 ++++++
 tests/index/test_hybrid_search.py           | 458 ++++++++++++++++++++
 5 files changed, 1061 insertions(+)
 create mode 100644 src/git_notes_memory/index/hybrid_search.py
 create mode 100644 tests/index/test_hybrid_search.py

diff --git a/src/git_notes_memory/index/__init__.py b/src/git_notes_memory/index/__init__.py
index 31bb842a..03fb3f5e 100644
--- a/src/git_notes_memory/index/__init__.py
+++ b/src/git_notes_memory/index/__init__.py
@@ -15,12 +15,19 @@
     >>> results = index.search_vector(query_embedding)
 """
 
+from .hybrid_search import HybridSearchEngine, HybridSearchResult
+from .rrf_fusion import RankedItem, RRFConfig, RRFFusionEngine
 from .schema_manager import SCHEMA_VERSION, SchemaManager
 from .search_engine import SearchEngine
 from .service import IndexService
 
 __all__ = [
+    "HybridSearchEngine",
+    "HybridSearchResult",
     "IndexService",
+    "RankedItem",
+    "RRFConfig",
+    "RRFFusionEngine",
     "SchemaManager",
     "SearchEngine",
     "SCHEMA_VERSION",
diff --git a/src/git_notes_memory/index/hybrid_search.py b/src/git_notes_memory/index/hybrid_search.py
new file mode 100644
index 00000000..be447bcc
--- /dev/null
+++ b/src/git_notes_memory/index/hybrid_search.py
@@ -0,0 +1,340 @@
+"""Hybrid Search Engine for combining vector and BM25 search with RRF.
+
+RET-H-002: Orchestrates multiple search strategies and combines results
+using Reciprocal Rank Fusion for improved retrieval accuracy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import logging
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from git_notes_memory.index.rrf_fusion import RankedItem, RRFConfig, RRFFusionEngine
+from git_notes_memory.observability.decorators import measure_duration
+from git_notes_memory.observability.metrics import get_metrics
+from git_notes_memory.observability.tracing import trace_operation
+from git_notes_memory.retrieval.config import HybridSearchConfig, SearchMode
+
+if TYPE_CHECKING:
+    from git_notes_memory.index.search_engine import SearchEngine
+    from git_notes_memory.models import Memory
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["HybridSearchEngine", "HybridSearchResult"]
+
+
+@dataclass(frozen=True)
+class HybridSearchResult:
+    """Result from hybrid search with RRF scoring.
+
+    Attributes:
+        memory: The memory object.
+        rrf_score: Combined RRF score from all sources.
+        sources: Dict mapping source names to their ranks for this result.
+        rank: Final rank in the combined results (1-indexed).
+    """
+
+    memory: Memory
+    rrf_score: float
+    sources: dict[str, int] = field(default_factory=dict)
+    rank: int = 0
+
+
+class HybridSearchEngine:
+    """Engine for combining multiple search strategies using RRF.
+
+    RET-H-002: This engine orchestrates vector similarity search and BM25
+    full-text search, then combines results using Reciprocal Rank Fusion
+    to leverage the strengths of both approaches.
+
+    The hybrid approach helps because:
+    - Vector search captures semantic similarity (synonyms, concepts)
+    - BM25 captures exact term matches (names, technical terms)
+    - RRF combines rankings without requiring score normalization
+
+    Example:
+        >>> engine = HybridSearchEngine(search_engine, embedding_fn, config)
+        >>> results = engine.search("PostgreSQL connection pooling", limit=10)
+        >>> for result in results:
+        ...     print(f"[{result.rank}] {result.memory.summary} (RRF: {result.rrf_score:.4f})")
+
+    Attributes:
+        config: Configuration for hybrid search behavior.
+    """
+
+    def __init__(
+        self,
+        search_engine: SearchEngine,
+        embed_fn: Callable[[str], Sequence[float]],
+        config: HybridSearchConfig | None = None,
+    ) -> None:
+        """Initialize the hybrid search engine.
+
+        Args:
+            search_engine: The underlying SearchEngine for vector/text search.
+            embed_fn: Function to generate embeddings from text.
+            config: Optional configuration. Uses defaults if not provided.
+        """
+        self._search_engine = search_engine
+        self._embed_fn = embed_fn
+        self._config = config or HybridSearchConfig()
+        self._rrf_engine = RRFFusionEngine(
+            RRFConfig(k=self._config.rrf_k, weights=self._config.get_rrf_weights())
+        )
+        self._executor = concurrent.futures.ThreadPoolExecutor(max_workers=2)
+
+    @property
+    def config(self) -> HybridSearchConfig:
+        """Get the current configuration."""
+        return self._config
+
+    @measure_duration("hybrid_search")
+    def search(
+        self,
+        query: str,
+        limit: int = 10,
+        mode: SearchMode | None = None,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[HybridSearchResult]:
+        """Search memories using hybrid vector + BM25 strategy.
+
+        Args:
+            query: The search query text.
+            limit: Maximum number of results to return.
+            mode: Search mode override. If None, uses config default.
+                - "hybrid": Combine vector and BM25 with RRF
+                - "vector": Vector search only
+                - "bm25": BM25 text search only
+            namespace: Optional namespace filter.
+            spec: Optional specification filter.
+            domain: Optional domain filter.
+
+        Returns:
+            List of HybridSearchResult objects sorted by RRF score descending.
+        """
+        metrics = get_metrics()
+        effective_mode = mode or self._config.mode
+
+        with trace_operation(
+            "hybrid_search.search",
+            labels={"mode": effective_mode, "limit": str(limit)},
+        ):
+            metrics.increment(
+                "hybrid_search_total",
+                labels={"mode": effective_mode},
+            )
+
+            if effective_mode == "vector":
+                return self._search_vector_only(query, limit, namespace, spec, domain)
+            elif effective_mode == "bm25":
+                return self._search_bm25_only(query, limit, namespace, spec, domain)
+            else:
+                return self._search_hybrid(query, limit, namespace, spec, domain)
+
+    def _search_hybrid(
+        self,
+        query: str,
+        limit: int,
+        namespace: str | None,
+        spec: str | None,
+        domain: str | None,
+    ) -> list[HybridSearchResult]:
+        """Perform hybrid search with RRF fusion."""
+        metrics = get_metrics()
+        max_per_source = self._config.max_results_per_source
+
+        # Get embedding for vector search
+        with trace_operation("hybrid_search.embed"):
+            query_embedding = self._embed_fn(query)
+
+        if self._config.parallel_search:
+            # Run searches in parallel using ThreadPoolExecutor
+            with trace_operation("hybrid_search.parallel"):
+                vector_future = self._executor.submit(
+                    self._search_engine.search_vector_ranked,
+                    query_embedding,
+                    k=max_per_source,
+                    namespace=namespace,
+                    spec=spec,
+                    domain=domain,
+                )
+                bm25_future = self._executor.submit(
+                    self._search_engine.search_text_ranked,
+                    query,
+                    limit=max_per_source,
+                    namespace=namespace,
+                    spec=spec,
+                    domain=domain,
+                )
+
+                vector_results = vector_future.result()
+                bm25_results = bm25_future.result()
+        else:
+            # Sequential search
+            vector_results = self._search_engine.search_vector_ranked(
+                query_embedding,
+                k=max_per_source,
+                namespace=namespace,
+                spec=spec,
+                domain=domain,
+            )
+            bm25_results = self._search_engine.search_text_ranked(
+                query,
+                limit=max_per_source,
+                namespace=namespace,
+                spec=spec,
+                domain=domain,
+            )
+
+        # Record per-source metrics
+        metrics.observe("hybrid_search_vector_results", len(vector_results))
+        metrics.observe("hybrid_search_bm25_results", len(bm25_results))
+
+        # Convert to RankedItems for RRF fusion
+        vector_ranked = [
+            RankedItem(
+                item_id=memory.id,
+                rank=rank,
+                score=score,
+                source="vector",
+                item=memory,
+            )
+            for memory, rank, score in vector_results
+        ]
+
+        bm25_ranked = [
+            RankedItem(
+                item_id=memory.id,
+                rank=rank,
+                score=score,
+                source="bm25",
+                item=memory,
+            )
+            for memory, rank, score in bm25_results
+        ]
+
+        # Fuse with RRF
+        with trace_operation("hybrid_search.rrf_fusion"):
+            fused = self._rrf_engine.fuse(
+                [("vector", vector_ranked), ("bm25", bm25_ranked)],
+                limit=limit,
+            )
+
+        # Convert to HybridSearchResult
+        results: list[HybridSearchResult] = []
+        for idx, fused_result in enumerate(fused):
+            if fused_result.item is not None:
+                results.append(
+                    HybridSearchResult(
+                        memory=fused_result.item,
+                        rrf_score=fused_result.rrf_score,
+                        sources=fused_result.sources,
+                        rank=idx + 1,
+                    )
+                )
+
+        return results
+
+    def _search_vector_only(
+        self,
+        query: str,
+        limit: int,
+        namespace: str | None,
+        spec: str | None,
+        domain: str | None,
+    ) -> list[HybridSearchResult]:
+        """Perform vector-only search."""
+        with trace_operation("hybrid_search.embed"):
+            query_embedding = self._embed_fn(query)
+
+        results = self._search_engine.search_vector_ranked(
+            query_embedding,
+            k=limit,
+            namespace=namespace,
+            spec=spec,
+            domain=domain,
+        )
+
+        return [
+            HybridSearchResult(
+                memory=memory,
+                rrf_score=1.0 / (self._config.rrf_k + rank),
+                sources={"vector": rank},
+                rank=rank,
+            )
+            for memory, rank, _score in results
+        ]
+
+    def _search_bm25_only(
+        self,
+        query: str,
+        limit: int,
+        namespace: str | None,
+        spec: str | None,
+        domain: str | None,
+    ) -> list[HybridSearchResult]:
+        """Perform BM25-only text search."""
+        results = self._search_engine.search_text_ranked(
+            query,
+            limit=limit,
+            namespace=namespace,
+            spec=spec,
+            domain=domain,
+        )
+
+        return [
+            HybridSearchResult(
+                memory=memory,
+                rrf_score=1.0 / (self._config.rrf_k + rank),
+                sources={"bm25": rank},
+                rank=rank,
+            )
+            for memory, rank, _score in results
+        ]
+
+    async def search_async(
+        self,
+        query: str,
+        limit: int = 10,
+        mode: SearchMode | None = None,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[HybridSearchResult]:
+        """Async version of search for use in async contexts.
+
+        Args:
+            query: The search query text.
+            limit: Maximum number of results to return.
+            mode: Search mode override.
+            namespace: Optional namespace filter.
+            spec: Optional specification filter.
+            domain: Optional domain filter.
+
+        Returns:
+            List of HybridSearchResult objects.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.search(query, limit, mode, namespace, spec, domain),
+        )
+
+    def close(self) -> None:
+        """Shutdown the thread pool executor."""
+        self._executor.shutdown(wait=False)
+
+    def __enter__(self) -> HybridSearchEngine:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit."""
+        self.close()
diff --git a/src/git_notes_memory/index/search_engine.py b/src/git_notes_memory/index/search_engine.py
index 3828cfaf..65e7905d 100644
--- a/src/git_notes_memory/index/search_engine.py
+++ b/src/git_notes_memory/index/search_engine.py
@@ -274,3 +274,117 @@ def _search_text_like(
             return [self._row_to_memory(row) for row in cursor.fetchall()]
         finally:
             cursor.close()
+
+    # =========================================================================
+    # Ranked Search Methods (for RRF fusion)
+    # =========================================================================
+
+    @measure_duration("index_search_vector_ranked")
+    def search_vector_ranked(
+        self,
+        query_embedding: Sequence[float],
+        k: int = 100,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[tuple[Memory, int, float]]:
+        """Search for similar memories and return with ranks.
+
+        RET-H-002: Returns ranked results suitable for RRF fusion.
+        Ranks are 1-indexed (first result has rank 1).
+
+        Args:
+            query_embedding: The query embedding vector.
+            k: Maximum number of results.
+            namespace: Optional namespace filter.
+            spec: Optional specification filter.
+            domain: Optional domain filter.
+
+        Returns:
+            List of (Memory, rank, distance) tuples sorted by distance ascending.
+            Rank is 1-indexed. Lower distance means more similar.
+        """
+        results = self.search_vector(
+            query_embedding, k=k, namespace=namespace, spec=spec, domain=domain
+        )
+        # Add 1-indexed ranks
+        return [(memory, idx + 1, distance) for idx, (memory, distance) in enumerate(results)]
+
+    @measure_duration("index_search_text_ranked")
+    def search_text_ranked(
+        self,
+        query: str,
+        limit: int = 100,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[tuple[Memory, int, float]]:
+        """Search memories by text and return with BM25 ranks.
+
+        RET-H-002: Returns ranked results suitable for RRF fusion.
+        Ranks are 1-indexed (first result has rank 1).
+
+        Args:
+            query: Text to search for.
+            limit: Maximum number of results.
+            namespace: Optional namespace filter.
+            spec: Optional specification filter.
+            domain: Optional domain filter.
+
+        Returns:
+            List of (Memory, rank, bm25_score) tuples sorted by relevance.
+            Rank is 1-indexed. Lower BM25 score means more relevant.
+        """
+        try:
+            return self._search_text_fts5_ranked(query, limit, namespace, spec, domain)
+        except sqlite3.OperationalError:
+            # FTS5 table doesn't exist - fall back to LIKE (no real scores)
+            memories = self._search_text_like(query, limit, namespace, spec, domain)
+            # Assign synthetic scores based on position
+            return [(memory, idx + 1, float(idx + 1)) for idx, memory in enumerate(memories)]
+
+    def _search_text_fts5_ranked(
+        self,
+        query: str,
+        limit: int,
+        namespace: str | None,
+        spec: str | None,
+        domain: str | None,
+    ) -> list[tuple[Memory, int, float]]:
+        """FTS5-based text search returning ranks and BM25 scores."""
+        fts_query = f'"{query}"'
+
+        sql = """
+            SELECT m.*, bm25(memories_fts) as bm25_score
+            FROM memories m
+            INNER JOIN memories_fts fts ON m.id = fts.id
+            WHERE memories_fts MATCH ?
+        """
+        params: list[object] = [fts_query]
+
+        if namespace is not None:
+            sql += " AND m.namespace = ?"
+            params.append(namespace)
+
+        if spec is not None:
+            sql += " AND m.spec = ?"
+            params.append(spec)
+
+        if domain is not None:
+            sql += " AND m.domain = ?"
+            params.append(domain)
+
+        sql += " ORDER BY bm25(memories_fts) LIMIT ?"
+        params.append(limit)
+
+        cursor = self._conn.cursor()
+        try:
+            cursor.execute(sql, params)
+            results: list[tuple[Memory, int, float]] = []
+            for idx, row in enumerate(cursor.fetchall()):
+                memory = self._row_to_memory(row)
+                bm25_score = row["bm25_score"]
+                results.append((memory, idx + 1, bm25_score))
+            return results
+        finally:
+            cursor.close()
diff --git a/src/git_notes_memory/recall.py b/src/git_notes_memory/recall.py
index 2e2789e9..59cbf4f3 100644
--- a/src/git_notes_memory/recall.py
+++ b/src/git_notes_memory/recall.py
@@ -33,6 +33,7 @@
     MemoryResult,
     SpecContext,
 )
+from git_notes_memory.retrieval.config import HybridSearchConfig, SearchMode
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -40,6 +41,10 @@
     from git_notes_memory.embedding import EmbeddingService
     from git_notes_memory.git_ops import GitOps
     from git_notes_memory.index import IndexService
+    from git_notes_memory.index.hybrid_search import (
+        HybridSearchEngine,
+        HybridSearchResult,
+    )
 
 __all__ = [
     "RecallService",
@@ -82,6 +87,7 @@ def __init__(
         index_service: IndexService | None = None,
         embedding_service: EmbeddingService | None = None,
         git_ops: GitOps | None = None,
+        hybrid_config: HybridSearchConfig | None = None,
     ) -> None:
         """Initialize the recall service.
 
@@ -94,15 +100,21 @@ def __init__(
                 If not provided, one will be created lazily.
             git_ops: Optional pre-configured GitOps instance.
                 If not provided, one will be created lazily.
+            hybrid_config: Optional hybrid search configuration.
+                If not provided, one will be created from environment variables.
         """
         # Use project-specific index for per-repository isolation
         self._index_path = index_path or get_project_index_path()
         self._index_service = index_service
         self._embedding_service = embedding_service
         self._git_ops = git_ops
+        self._hybrid_config = hybrid_config
         # RES-M-001: Lock for thread-safe user index initialization
         self._user_index_lock = threading.Lock()
         self._user_index_service: IndexService | None = None
+        # RET-H-002: Lazy-initialized hybrid search engine
+        self._hybrid_engine: HybridSearchEngine | None = None
+        self._hybrid_engine_lock = threading.Lock()
 
     @property
     def index_path(self) -> Path:
@@ -159,6 +171,54 @@ def _get_git_ops_for_memory(self, memory: Memory) -> GitOps:
             return self._get_user_git_ops()
         return self._get_git_ops()
 
+    def _get_hybrid_engine(self) -> HybridSearchEngine:
+        """Get or create the HybridSearchEngine instance.
+
+        RET-H-002: Thread-safe lazy initialization using double-checked locking.
+
+        Returns:
+            HybridSearchEngine configured for hybrid search.
+        """
+        # Fast path: return existing instance without lock
+        if self._hybrid_engine is not None:
+            return self._hybrid_engine
+
+        # Slow path: acquire lock and create if still None
+        with self._hybrid_engine_lock:
+            if self._hybrid_engine is None:
+                from git_notes_memory.index.hybrid_search import HybridSearchEngine
+
+                # Get or create hybrid config
+                config = self._hybrid_config or HybridSearchConfig.from_env()
+
+                # Create embedding function from embedding service
+                embedding_service = self._get_embedding()
+
+                def embed_fn(text: str) -> list[float]:
+                    return list(embedding_service.embed(text))
+
+                # Get search engine from index service
+                index = self._get_index()
+                # Access internal search engine (guaranteed non-None after initialize())
+                search_engine = index._search_engine
+                if search_engine is None:
+                    msg = "SearchEngine not initialized"
+                    raise RecallError(msg, "Call index.initialize() first")
+
+                self._hybrid_engine = HybridSearchEngine(
+                    search_engine=search_engine,
+                    embed_fn=embed_fn,
+                    config=config,
+                )
+        return self._hybrid_engine
+
+    @property
+    def hybrid_config(self) -> HybridSearchConfig:
+        """Get the hybrid search configuration."""
+        if self._hybrid_config is None:
+            self._hybrid_config = HybridSearchConfig.from_env()
+        return self._hybrid_config
+
     # -------------------------------------------------------------------------
     # Search Operations
     # -------------------------------------------------------------------------
@@ -259,6 +319,88 @@ def search(
                 "Check query text and try again",
             ) from e
 
+    def search_hybrid(
+        self,
+        query: str,
+        k: int = 10,
+        *,
+        mode: SearchMode | None = None,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: Domain | None = None,
+    ) -> list[HybridSearchResult]:
+        """Search for memories using hybrid vector + BM25 strategy with RRF fusion.
+
+        RET-H-002: Uses Reciprocal Rank Fusion to combine vector similarity
+        and BM25 text search results for improved retrieval accuracy.
+
+        Args:
+            query: The search query text.
+            k: Maximum number of results to return.
+            mode: Search mode. Options:
+                - "hybrid": Combine vector and BM25 with RRF (default)
+                - "vector": Vector search only
+                - "bm25": BM25 text search only
+            namespace: Optional namespace to filter results.
+            spec: Optional specification to filter results.
+            domain: Optional domain filter. Currently only supports project domain.
+                User domain hybrid search is not yet supported.
+
+        Returns:
+            List of HybridSearchResult objects sorted by RRF score descending.
+
+        Raises:
+            RecallError: If the search operation fails.
+
+        Examples:
+            >>> results = service.search_hybrid("authentication flow")
+            >>> for r in results:
+            ...     print(f"[{r.rank}] {r.memory.summary} (RRF: {r.rrf_score:.4f})")
+            ...     print(f"  Sources: {r.sources}")
+
+            >>> # Vector-only mode
+            >>> results = service.search_hybrid("API design", mode="vector")
+
+            >>> # BM25-only mode
+            >>> results = service.search_hybrid("PostgreSQL", mode="bm25")
+        """
+        if not query or not query.strip():
+            return []
+
+        try:
+
+            # Get the hybrid search engine
+            engine = self._get_hybrid_engine()
+
+            # Perform hybrid search (currently project domain only)
+            domain_str = domain.value if domain else None
+
+            results = engine.search(
+                query=query,
+                limit=k,
+                mode=mode,
+                namespace=namespace,
+                spec=spec,
+                domain=domain_str,
+            )
+
+            logger.debug(
+                "Hybrid search for '%s' returned %d results (k=%d, mode=%s, namespace=%s)",
+                query[:50],
+                len(results),
+                k,
+                mode or engine.config.mode,
+                namespace,
+            )
+
+            return results
+
+        except Exception as e:
+            raise RecallError(
+                f"Hybrid search failed: {e}",
+                "Check query text and try again",
+            ) from e
+
     def _search_single_domain(
         self,
         query_embedding: Sequence[float],
diff --git a/tests/index/test_hybrid_search.py b/tests/index/test_hybrid_search.py
new file mode 100644
index 00000000..812f0303
--- /dev/null
+++ b/tests/index/test_hybrid_search.py
@@ -0,0 +1,458 @@
+"""Tests for the Hybrid Search Engine.
+
+Tests cover:
+- Basic hybrid search functionality
+- Mode selection (hybrid, vector, bm25)
+- RRF fusion integration
+- Parallel vs sequential search
+- Configuration options
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from unittest.mock import MagicMock
+
+import pytest
+
+from git_notes_memory.index.hybrid_search import HybridSearchEngine, HybridSearchResult
+from git_notes_memory.models import Memory
+from git_notes_memory.retrieval.config import HybridSearchConfig
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@dataclass
+class MockSearchEngine:
+    """Mock search engine for testing."""
+
+    vector_results: list[tuple[Memory, int, float]]
+    text_results: list[tuple[Memory, int, float]]
+
+    def search_vector_ranked(
+        self,
+        query_embedding: list[float],
+        k: int = 100,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[tuple[Memory, int, float]]:
+        """Return mock vector results."""
+        return self.vector_results[:k]
+
+    def search_text_ranked(
+        self,
+        query: str,
+        limit: int = 100,
+        namespace: str | None = None,
+        spec: str | None = None,
+        domain: str | None = None,
+    ) -> list[tuple[Memory, int, float]]:
+        """Return mock text results."""
+        return self.text_results[:limit]
+
+
+def make_memory(memory_id: str, summary: str = "Test") -> Memory:
+    """Create a test memory."""
+    return Memory(
+        id=memory_id,
+        commit_sha="abc1234",
+        namespace="test",
+        summary=summary,
+        content="Test content",
+        timestamp=datetime.now(UTC),
+        tags=(),
+    )
+
+
+@pytest.fixture
+def memories() -> dict[str, Memory]:
+    """Create a set of test memories."""
+    return {
+        "mem1": make_memory("mem1", "PostgreSQL connection pooling"),
+        "mem2": make_memory("mem2", "Database optimization strategies"),
+        "mem3": make_memory("mem3", "Redis caching implementation"),
+        "mem4": make_memory("mem4", "API rate limiting design"),
+    }
+
+
+@pytest.fixture
+def mock_embed_fn() -> callable:
+    """Create a mock embedding function."""
+    return lambda _text: [0.1] * 384
+
+
+@pytest.fixture
+def mock_search_engine(memories: dict[str, Memory]) -> MockSearchEngine:
+    """Create a mock search engine with preset results."""
+    # Vector search: mem1 first, mem2 second
+    vector_results = [
+        (memories["mem1"], 1, 0.1),
+        (memories["mem2"], 2, 0.2),
+        (memories["mem3"], 3, 0.3),
+    ]
+    # BM25 search: mem2 first, mem1 second (different order)
+    text_results = [
+        (memories["mem2"], 1, -10.0),
+        (memories["mem1"], 2, -8.0),
+        (memories["mem4"], 3, -6.0),
+    ]
+    return MockSearchEngine(vector_results, text_results)
+
+
+@pytest.fixture
+def hybrid_engine(
+    mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+) -> HybridSearchEngine:
+    """Create a hybrid search engine with mocks."""
+    return HybridSearchEngine(mock_search_engine, mock_embed_fn)
+
+
+# =============================================================================
+# Test: Basic Hybrid Search
+# =============================================================================
+
+
+class TestBasicHybridSearch:
+    """Test basic hybrid search functionality."""
+
+    def test_hybrid_search_returns_results(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that hybrid search returns results."""
+        results = hybrid_engine.search("PostgreSQL", limit=10)
+        assert len(results) > 0
+        assert all(isinstance(r, HybridSearchResult) for r in results)
+
+    def test_hybrid_search_result_structure(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test HybridSearchResult structure."""
+        results = hybrid_engine.search("PostgreSQL", limit=10)
+        result = results[0]
+
+        assert result.memory is not None
+        assert result.rrf_score > 0
+        assert result.rank >= 1
+        assert isinstance(result.sources, dict)
+
+    def test_hybrid_fuses_vector_and_bm25(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that hybrid mode combines both search strategies."""
+        results = hybrid_engine.search("PostgreSQL", limit=10)
+
+        # Check that results come from both sources
+        all_sources: set[str] = set()
+        for r in results:
+            all_sources.update(r.sources.keys())
+
+        assert "vector" in all_sources
+        assert "bm25" in all_sources
+
+    def test_items_in_both_sources_rank_higher(
+        self, hybrid_engine: HybridSearchEngine, memories: dict[str, Memory]
+    ) -> None:
+        """Test that items appearing in both sources get higher RRF scores."""
+        results = hybrid_engine.search("PostgreSQL", limit=10)
+
+        # mem1 and mem2 appear in both sources, should be ranked higher
+        top_ids = {r.memory.id for r in results[:2]}
+        assert "mem1" in top_ids or "mem2" in top_ids
+
+
+# =============================================================================
+# Test: Mode Selection
+# =============================================================================
+
+
+class TestModeSelection:
+    """Test search mode selection."""
+
+    def test_vector_only_mode(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test vector-only search mode."""
+        config = HybridSearchConfig(mode="vector")
+        engine = HybridSearchEngine(mock_search_engine, mock_embed_fn, config)
+
+        results = engine.search("test")
+
+        # Should only have vector sources
+        for r in results:
+            assert "vector" in r.sources
+            assert "bm25" not in r.sources
+
+    def test_bm25_only_mode(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test BM25-only search mode."""
+        config = HybridSearchConfig(mode="bm25")
+        engine = HybridSearchEngine(mock_search_engine, mock_embed_fn, config)
+
+        results = engine.search("test")
+
+        # Should only have bm25 sources
+        for r in results:
+            assert "bm25" in r.sources
+            assert "vector" not in r.sources
+
+    def test_mode_override_in_search(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that mode can be overridden per search call."""
+        # Default is hybrid
+        hybrid_results = hybrid_engine.search("test")
+        assert len({s for r in hybrid_results for s in r.sources}) >= 1
+
+        # Override to vector only
+        vector_results = hybrid_engine.search("test", mode="vector")
+        for r in vector_results:
+            assert "bm25" not in r.sources
+
+
+# =============================================================================
+# Test: RRF Score Calculations
+# =============================================================================
+
+
+class TestRRFScores:
+    """Test RRF score calculations in hybrid search."""
+
+    def test_rrf_scores_are_positive(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that RRF scores are positive."""
+        results = hybrid_engine.search("test")
+        for r in results:
+            assert r.rrf_score > 0
+
+    def test_results_sorted_by_rrf_score(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that results are sorted by RRF score descending."""
+        results = hybrid_engine.search("test")
+
+        for i in range(len(results) - 1):
+            assert results[i].rrf_score >= results[i + 1].rrf_score
+
+    def test_rank_matches_position(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that ranks match 1-indexed positions."""
+        results = hybrid_engine.search("test")
+
+        for i, r in enumerate(results):
+            assert r.rank == i + 1
+
+
+# =============================================================================
+# Test: Configuration Options
+# =============================================================================
+
+
+class TestConfiguration:
+    """Test configuration options."""
+
+    def test_custom_rrf_k(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test custom RRF k parameter."""
+        config = HybridSearchConfig(rrf_k=100)
+        engine = HybridSearchEngine(mock_search_engine, mock_embed_fn, config)
+
+        results = engine.search("test")
+
+        # With k=100, score for rank 1 = 1/(100+1) = 0.0099...
+        # Check that scores reflect the higher k
+        assert results[0].rrf_score < 0.02  # Lower than k=60
+
+    def test_parallel_search_disabled(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test sequential search when parallel is disabled."""
+        config = HybridSearchConfig(parallel_search=False)
+        engine = HybridSearchEngine(mock_search_engine, mock_embed_fn, config)
+
+        results = engine.search("test")
+
+        # Should still return results
+        assert len(results) > 0
+
+    def test_max_results_per_source(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test max_results_per_source limits."""
+        config = HybridSearchConfig(max_results_per_source=2)
+        engine = HybridSearchEngine(mock_search_engine, mock_embed_fn, config)
+
+        # Even with high limit, should only get max 2 from each source
+        results = engine.search("test", limit=100)
+
+        # Max 4 unique results (2 from vector + 2 from bm25, some may overlap)
+        assert len(results) <= 4
+
+
+# =============================================================================
+# Test: Limit Handling
+# =============================================================================
+
+
+class TestLimitHandling:
+    """Test result limit handling."""
+
+    def test_respects_limit(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test that limit is respected."""
+        results = hybrid_engine.search("test", limit=2)
+        assert len(results) <= 2
+
+    def test_limit_one(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test limit of 1."""
+        results = hybrid_engine.search("test", limit=1)
+        assert len(results) == 1
+
+
+# =============================================================================
+# Test: Edge Cases
+# =============================================================================
+
+
+class TestEdgeCases:
+    """Test edge cases."""
+
+    def test_empty_results(self, mock_embed_fn: callable) -> None:
+        """Test search with no results."""
+        empty_engine = MockSearchEngine([], [])
+        engine = HybridSearchEngine(empty_engine, mock_embed_fn)
+
+        results = engine.search("test")
+        assert results == []
+
+    def test_only_vector_results(
+        self, mock_embed_fn: callable, memories: dict[str, Memory]
+    ) -> None:
+        """Test when only vector search returns results."""
+        vector_only = MockSearchEngine(
+            [(memories["mem1"], 1, 0.1)],
+            [],
+        )
+        engine = HybridSearchEngine(vector_only, mock_embed_fn)
+
+        results = engine.search("test")
+        assert len(results) == 1
+        assert results[0].memory.id == "mem1"
+
+    def test_only_bm25_results(
+        self, mock_embed_fn: callable, memories: dict[str, Memory]
+    ) -> None:
+        """Test when only BM25 search returns results."""
+        bm25_only = MockSearchEngine(
+            [],
+            [(memories["mem2"], 1, -10.0)],
+        )
+        engine = HybridSearchEngine(bm25_only, mock_embed_fn)
+
+        results = engine.search("test")
+        assert len(results) == 1
+        assert results[0].memory.id == "mem2"
+
+
+# =============================================================================
+# Test: Context Manager
+# =============================================================================
+
+
+class TestContextManager:
+    """Test context manager functionality."""
+
+    def test_context_manager_usage(
+        self, mock_search_engine: MockSearchEngine, mock_embed_fn: callable
+    ) -> None:
+        """Test using HybridSearchEngine as context manager."""
+        with HybridSearchEngine(mock_search_engine, mock_embed_fn) as engine:
+            results = engine.search("test")
+            assert len(results) > 0
+
+
+# =============================================================================
+# Test: Async Search
+# =============================================================================
+
+
+class TestAsyncSearch:
+    """Test async search functionality."""
+
+    @pytest.mark.asyncio
+    async def test_async_search(
+        self, hybrid_engine: HybridSearchEngine
+    ) -> None:
+        """Test async search method."""
+        results = await hybrid_engine.search_async("test", limit=5)
+        assert len(results) > 0
+        assert all(isinstance(r, HybridSearchResult) for r in results)
+
+
+# =============================================================================
+# Test: Filter Passthrough
+# =============================================================================
+
+
+class TestFilterPassthrough:
+    """Test that filters are passed to underlying search methods."""
+
+    def test_namespace_filter(
+        self, mock_embed_fn: callable, memories: dict[str, Memory]
+    ) -> None:
+        """Test namespace filter is passed through."""
+        search_engine = MagicMock()
+        search_engine.search_vector_ranked.return_value = [
+            (memories["mem1"], 1, 0.1)
+        ]
+        search_engine.search_text_ranked.return_value = []
+
+        engine = HybridSearchEngine(search_engine, mock_embed_fn)
+        engine.search("test", namespace="decisions")
+
+        # Check that namespace was passed
+        search_engine.search_vector_ranked.assert_called_once()
+        call_args = search_engine.search_vector_ranked.call_args
+        assert call_args.kwargs.get("namespace") == "decisions"
+
+    def test_spec_filter(
+        self, mock_embed_fn: callable, memories: dict[str, Memory]
+    ) -> None:
+        """Test spec filter is passed through."""
+        search_engine = MagicMock()
+        search_engine.search_vector_ranked.return_value = [
+            (memories["mem1"], 1, 0.1)
+        ]
+        search_engine.search_text_ranked.return_value = []
+
+        engine = HybridSearchEngine(search_engine, mock_embed_fn)
+        engine.search("test", spec="my-project")
+
+        call_args = search_engine.search_vector_ranked.call_args
+        assert call_args.kwargs.get("spec") == "my-project"
+
+    def test_domain_filter(
+        self, mock_embed_fn: callable, memories: dict[str, Memory]
+    ) -> None:
+        """Test domain filter is passed through."""
+        search_engine = MagicMock()
+        search_engine.search_vector_ranked.return_value = [
+            (memories["mem1"], 1, 0.1)
+        ]
+        search_engine.search_text_ranked.return_value = []
+
+        engine = HybridSearchEngine(search_engine, mock_embed_fn)
+        engine.search("test", domain="user")
+
+        call_args = search_engine.search_vector_ranked.call_args
+        assert call_args.kwargs.get("domain") == "user"