feat(memory): pluggable semantic embeddings via go-vector v1.3.0 HTTPEmbedder

Replace the hardwired RandomProjections usage across all memory similarity
paths with a textEmbedder seam. The default stays RP (local, zero-cost,
unchanged behavior); a new memory.embedding config section routes episode
recall, episode dedup, the non-LLM ranker, and fact merge-on-write through
any OpenAI-compatible embeddings API (Ollama, llama.cpp, OpenAI, ...) for
real semantic similarity instead of bag-of-words overlap.

- internal/memory/embedder.go: EmbeddingConfig + textEmbedder interface;
  rpTextEmbedder (corpus-fitted, bigram-featurized) and httpTextEmbedder
  (stateless, raw text, text->vector cache, batch misses-only refits).
- episode_index.go: index owns a textEmbedder; persisted vectors carry an
  embedding-space fingerprint (episodes_index_meta.json) so switching
  provider/model/dims rebuilds automatically while legacy RP gobs keep
  loading; failed rebuilds back off 30s so a down backend is never re-hit
  on every loop turn.
- episodes.go: embedder factory on EpisodeStore; findDuplicate and the
  embedder ranker fail safe (no dedup / recency order) on embed errors.
- merge.go: MergeDetector classifies over the configured embedder; embed
  failures degrade to "nobody" (add without merge) instead of misclassifying.
- config: memory.embedding overlay in resolveMemory + NewMemoryManager;
  ${ENV_VAR} expansion for base_url/api_key; 10s default timeout.
- docs: CONFIG.md field reference + MEMORY.md mechanics/privacy notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jkyberneees

docs/CONFIG.md

@@ -206,7 +206,15 @@ The `memory` section controls the persistent memory system (see [docs/MEMORY.md]
     "auto_approve_episodes": false,
     "episode_dedup_threshold": 0.92,
     "max_episodes": 500,
-    "episode_ttl_days": 0
+    "episode_ttl_days": 0,
+    "embedding": {
+      "provider": "http",
+      "base_url": "http://localhost:11434/v1",
+      "model": "nomic-embed-text",
+      "api_key": "${OPENAI_API_KEY}",
+      "dims": 0,
+      "timeout_seconds": 10
+    }
   }
 }
 ```
@@ -231,6 +239,39 @@ The `memory` section controls the persistent memory system (see [docs/MEMORY.md]
 | `episode_dedup_threshold` | 0.92 | Cosine similarity above which a newly written episode is treated as a near-duplicate of an existing one and **replaces** it (newest wins). An untrusted episode never replaces a trusted/approved one. `0` disables dedup. |
 | `max_episodes` | 500 | Maximum number of stored episodes. On each write, episodes beyond this count are evicted oldest-first (both the summary file and the index entry). `0` disables the cap. |
 | `episode_ttl_days` | 0 | Evict episodes older than this many days. `0` (default) disables TTL-based eviction. |
+| `embedding` | *(unset)* | Semantic embedding backend for episode recall, episode dedup, the non-LLM episode ranker, and fact merge-on-write. Unset = local RandomProjections (lexical bag-of-words — fast, zero-cost, but no real semantics). See below. |
+
+### `embedding` — real semantic embeddings (optional)
+
+By default every similarity computation in memory uses go-vector
+**RandomProjections**: a local, zero-dependency bag-of-words embedder. It is
+fast but purely lexical — *"fixed the auth bug"* and *"repaired login issue"*
+share no tokens and score ~0. Setting `embedding.provider` to `"http"` routes
+all of those paths through any **OpenAI-compatible embeddings API** instead
+(Ollama, llama.cpp server, LM Studio, vLLM, OpenAI, Voyage…), giving recall
+that matches by meaning.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `provider` | `"rp"` | `"rp"` = local RandomProjections; `"http"` = OpenAI-compatible embeddings API. An `"http"` config missing `base_url` or `model` silently falls back to `"rp"` so memory keeps working. |
+| `base_url` | — | API root, e.g. `http://localhost:11434/v1` (Ollama) or `https://api.openai.com/v1`. `${ENV_VAR}` expansion supported. |
+| `model` | — | Embedding model name, e.g. `nomic-embed-text`, `text-embedding-3-small`. |
+| `api_key` | — | Sent as `Authorization: Bearer <key>` when set. `${ENV_VAR}` expansion supported — keep secrets out of config files. |
+| `dims` | 0 | Expected vector dimensionality; `0` infers it from the first response (recommended). |
+| `timeout_seconds` | 10 | Per-request HTTP timeout. |
+
+Operational notes:
+
+- **Per-turn recall stays cheap.** Episode vectors are cached in a persisted
+  index; a loop turn costs at most one embedding call (the query), bounded by
+  `timeout_seconds`. If the backend is down, recall degrades to "no context"
+  and rebuilds back off for 30s — the agent loop is never blocked.
+- **Switching backends is safe.** The persisted index records which embedding
+  space it was built in; changing `provider`/`model`/`dims` automatically
+  invalidates it and rebuilds on next use (one batch embedding call).
+- **Episode summaries leave the machine.** With `"http"`, episode summaries and
+  fact entries are sent to the configured endpoint for embedding. Point it at a
+  local server (Ollama/llama.cpp) if that must not happen.
 
 ### ⚠️ `extract_facts` — automatic fact learning (opt-in, off by default)
 

docs/MEMORY.md

@@ -90,7 +90,7 @@ RP.embed(newEntry) → cos similarity vs each existing entry
 
 This saves ~80% of LLM calls on memory writes.
 
-**Implementation:** `internal/memory/merge.go` imports `github.com/BackendStack21/go-vector/pkg/vector` for `RandomProjections` and `Cosine`. The RP embedder is fit on existing facts when the detector is created, and re-fit whenever facts change.
+**Implementation:** `internal/memory/merge.go` imports `github.com/BackendStack21/go-vector/pkg/vector` for `RandomProjections` and `Cosine`. The embedder is fit on existing facts when the detector is created, and re-fit whenever facts change. With `memory.embedding` configured (see *Pluggable Embeddings* below), the same classification runs over real semantic vectors from an OpenAI-compatible API instead of RP.
 
 ### Durability & Statefulness
 
@@ -207,11 +207,53 @@ The episode index (`episodes/index.json`) is cached in memory after the first re
 
 ### Search Ranking
 
-Episode search uses **RandomProjections** (go-vector) for semantic similarity by default:
+Episode search uses **RandomProjections** (go-vector) for similarity by default:
 
 1. Fit RP embedder on episode summaries + query (64 dims, ~1ms)
 2. Embed each summary and the query into 64-dimensional vectors
 3. Score by cosine similarity between query vector and each summary vector
 4. Return top-3 results sorted by score
 
 This is zero LLM calls per search, ~1ms per search. Set `llm_search: true` in config to switch to LLM-based ranking (uses SimpleCall to rank episodes by relevance — higher quality, higher latency + token cost).
+
+### Pluggable Embeddings (`memory.embedding`)
+
+RandomProjections is lexical: two texts only score as similar when they share
+vocabulary. *"fixed the auth bug"* vs *"repaired login issue"* → cosine ≈ 0,
+so recall misses semantically related episodes. The `memory.embedding` config
+section replaces RP with a real embedding model behind any OpenAI-compatible
+API (Ollama, llama.cpp server, LM Studio, vLLM, OpenAI, …):
+
+```json
+{
+  "memory": {
+    "embedding": {
+      "provider": "http",
+      "base_url": "http://localhost:11434/v1",
+      "model": "nomic-embed-text"
+    }
+  }
+}
+```
+
+One config switches **every** similarity path: per-turn episode recall, the
+explicit `memory(search=...)` candidate retrieval, episode write-time dedup,
+the non-LLM episode ranker, and fact merge-on-write classification.
+
+Mechanics (`internal/memory/embedder.go`):
+
+- All paths go through the `textEmbedder` seam — `rp` (default, corpus-fitted,
+  bigram-featurized) or `http` (stateless, raw text, cached).
+- The persisted episode vector index records its embedding space in
+  `episodes_index_meta.json`; changing provider/model/dims invalidates and
+  rebuilds it automatically. Pre-existing RP indexes (no meta file) keep
+  loading without a rebuild.
+- The HTTP embedder caches text→vector, so an index rebuild after a new
+  episode only embeds texts it hasn't seen — one batch call.
+- Failure mode: embedding errors degrade to "no recall context" / "add fact
+  without merge check"; a failed index rebuild backs off for 30s so a down
+  backend is not re-hit every loop turn. The agent loop is never blocked.
+
+See `docs/CONFIG.md` → `embedding` for all fields and the privacy note
+(summaries are sent to the configured endpoint — use a local server if that
+matters).

go.mod

@@ -4,7 +4,7 @@ go 1.25.0
 
 require (
 	github.com/BackendStack21/go-mcp v1.1.0
-	github.com/BackendStack21/go-vector v1.2.0
+	github.com/BackendStack21/go-vector v1.3.0
 	golang.org/x/net v0.54.0
 	golang.org/x/term v0.43.0
 )

go.sum

@@ -1,9 +1,7 @@
 github.com/BackendStack21/go-mcp v1.1.0 h1:NQStOkqUWjzzzmySnfFHvPKhbKr92iBuPJjkNpb0MIU=
 github.com/BackendStack21/go-mcp v1.1.0/go.mod h1:RKFw6nrl6ySQqqrR8KtG7HYZ/heyyjT8SjiEtlbTMY8=
-github.com/BackendStack21/go-vector v1.1.1 h1:sycI+a/ifT2DD3kdH0HleWtjKmIVNutvL/pgOL9qTA8=
-github.com/BackendStack21/go-vector v1.1.1/go.mod h1:+IzfAFO4m6xrjsOhZsiTAbMbm8+hX0d9C1uD0SGPzHc=
-github.com/BackendStack21/go-vector v1.2.0 h1:Zq6J/x7/OlAmVYC5t6VX64cf6V9rkSU2sR6nz49Fu+I=
-github.com/BackendStack21/go-vector v1.2.0/go.mod h1:+IzfAFO4m6xrjsOhZsiTAbMbm8+hX0d9C1uD0SGPzHc=
+github.com/BackendStack21/go-vector v1.3.0 h1:VT1cwPAUzkg3Rt0fXA+jTzW472jgObqs85/TcPs4N7Q=
+github.com/BackendStack21/go-vector v1.3.0/go.mod h1:TkxZEqKGeN38QNWUoQt4xJcf6n2kI1pY7nu6ibXK1Yo=
 golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
 golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
 golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=

internal/config/loader.go

@@ -924,6 +924,9 @@ func resolveMemory(cfg *memory.MemoryConfig) memory.MemoryConfig {
 	if cfg.EpisodeTTLDays > 0 {
 		def.EpisodeTTLDays = cfg.EpisodeTTLDays
 	}
+	if cfg.Embedding != nil {
+		def.Embedding = cfg.Embedding
+	}
 	return def
 }