Phase 3: Brain Mode — Hybrid Search (usearch + RRF)

[ajianaz]

Phase 3: Brain Mode — Hybrid Search (usearch + RRF)

Scope

• usearch vector index (HNSW, cosine) — same pattern as uteke
• Index-time embedding (static token → 768d, existing embed/ module)
• cora brain <query> — hybrid search: FTS5 + usearch KNN + graph proximity → RRF fusion (k=60)
• cora review --brain — auto-enrich review context with semantic neighbors
• .cora.yaml embedding config (tier, dimensions, index-time)
• MCP tool: brain_search
• Schema v4: embedding metadata on projects table

Architecture

cora brain <query>
  ├─ FTS5 keyword search (existing symbols table)
  ├─ usearch vector KNN (new: cora_index.usearch)
  └─ Graph proximity BFS (existing edges table)
  → RRF Fusion (k=60) → ranked results + provenance

Storage

• ~/.codecora/cora-code/graph.db — SQLite (symbols, edges, projects)
• ~/.codecora/cora-code/cora_index.usearch — HNSW vector index (new)

New Dependencies

• usearch = "2" — HNSW vector index (same as uteke)
• fs2 = "0.4" — file locking (same as uteke)

Implementation Checklist

• Add usearch + fs2 to Cargo.toml
• Create src/index/vector.rs — CodeVectorIndex (copy pattern from uteke vector.rs, simplified)
• Schema v4 migration: ALTER TABLE projects ADD COLUMN embedding_tier/dims/last_embedded_at
• Wire index-time embedding into index_file() pipeline
• Implement brain_search() — FTS5 + usearch + graph → RRF (k=60)
• Add Brain command to CLI (cora brain <query>)
• Wire cora review --brain context enrichment
• Add MCP tool brain_search
• .cora.yaml config: embedding.tier, embedding.dimensions
• Tests: vector index, brain search, RRF fusion
• Manual test on cora-code repo

Effort

~1,070 lines

Depends On

• Phase 2 (tree-sitter, schema v3, edges) — ✅ Done
• Phase 1 (static token embedding) — ✅ Done (embed/ module exists, unwired)