feat(search): pluggable vector/embedding search with hybrid FTS5+RRF

[jtomaszon]

Summary

Adds semantic search capability alongside existing FTS5 keyword search, following the architecture endorsed in #21 and #24.

• New internal/embedding/ package — Provider interface with Ollama and OpenAI implementations. Pure-Go cosine similarity, binary serialization, and Reciprocal Rank Fusion (RRF) merge. No new dependencies beyond net/http.
• Hybrid search — When an embedding provider is configured, Search() runs FTS5 + vector cosine similarity and merges results via RRF (k=60). Falls back to FTS5-only when no provider is set — zero overhead for existing users.
• Async embedding on save/update — AddObservation and UpdateObservation trigger background embedding generation. Content changes re-embed automatically.
• observation_embeddings table — Created on migration, nullable. Separate from observations to keep FTS5 scans fast.
• CLI flags — --embedding-provider=ollama|openai|none, --embedding-model, --embedding-url, plus ENGRAM_EMBEDDING_* env vars.
• engram backfill-embeddings — Bulk-embeds existing observations that don't have embeddings yet.

Context

This implements the approach discussed by @Gentleman-Programming in #21 and #24:

1. FTS5 stays default — zero overhead when no provider configured
2. Vector search as opt-in via pluggable providers
3. Hybrid search merging FTS5 + vector results

Design decisions

Decision	Rationale
FTS5 stays default	Existing behavior unchanged when no provider configured
Brute-force cosine	Personal memory is typically <10K obs. Benchmark: 564ns/op on 768-dim (56ms for 100K obs)
RRF over weighted linear	Rank-based, no need to normalize BM25 and cosine to same scale
Separate embeddings table	Large BLOBs (~3KB each) would bloat observation table scans
Async embedding	Network calls (50-500ms) shouldn't block observation saves
No new Go deps	Providers use stdlib net/http only. CGO_ENABLED=0 preserved
Agent-agnostic providers	Users plug Ollama (local/free) or OpenAI (cloud) via config

Stats

• 1,495 lines added across 9 files (6 new + 3 modified)
• 33 new tests (22 embedding + 11 store integration)
• All 346 existing tests pass — zero regressions
• Benchmark: BenchmarkCosineSimilarity768: 564.5 ns/op, 0 allocs

Refs #21, #24

Test plan

• All existing 346 tests pass unchanged
• New embedding provider tests with mock HTTP servers
• Cosine similarity correctness (identical=1, orthogonal=0, opposite=-1)
• RRF merge ordering verified with known inputs
• Store integration: hybrid search returns results from both FTS5 and vector
• Store integration: vector search respects project/scope/type filters
• Backfill generates embeddings for all unembedded observations
• No-provider path returns FTS5-only results (backward compatible)
• Embedding table created on migration

🤖 Generated with Claude Code

[Alan-TheGentleman]

Hola @jtomaszon! 👋

Primero que nada, quiero reconocer que esto es un laburazo. La idea de pluggable vector/embedding search con hybrid FTS5+RRF es ambiciosa y está muy bien pensada. El approach de mantener FTS5 como default con zero overhead, vector search opt-in, y RRF para el merge es exactamente la dirección que queremos. Se nota que le metiste cabeza a las decisiones de diseño (brute-force cosine para <10K obs, tabla separada de embeddings, async embedding, sin deps nuevas). Muy sólido.

El tema: el PR tiene conflictos de merge con main que hay que resolver antes de que podamos avanzar con el review. Necesito pedirte que hagas un rebase sobre el main actual y resuelvas los conflictos.

git fetch origin
git rebase origin/main
# resolver conflictos
git push --force-with-lease

Una vez que los conflictos estén resueltos, nos sentamos a hacer un review arquitectónico completo y detallado. Hay mucho para mirar (1,495 líneas nuevas, 9 archivos, 33 tests) y quiero darle la atención que se merece.

Dale para adelante con el rebase y avisame cuando esté listo. Estamos acá para lo que necesites.

[Alan-TheGentleman]

¡Buenas! Primero que nada, se nota el laburo que le metiste a esto — es un PR serio, bien armado, y eso se respeta mucho.

Pero tengo que ser directo: la filosofía core de engram es un solo binario + una sola base de datos SQLite + cero dependencias externas. Es así de simple y es así de poderoso. Requerir Ollama u OpenAI para la búsqueda rompe ese principio fundamental.

La gracia de engram es que lo instalás y funciona. No tenés que levantar Ollama, no tenés que configurar API keys de OpenAI, no tenés que manejar modelos de embedding. Un binario, un archivo SQLite, y listo.

Como referencia, hay otro PR (#170) que propone búsqueda por SimHash — un approach puramente local, sin dependencias externas. Eso se alinea más con la filosofía, aunque también necesita pasar por el proceso de discusión en un issue primero.

Si te interesa seguir contribuyendo (y ojalá que sí), considerá approaches que se mantengan dentro de esa filosofía: todo local, todo autocontenido, sin servicios externos.

Gracias de verdad por el esfuerzo, y disculpá que no podamos mergear esto. ¡Las puertas están abiertas para futuras contribuciones!