Skills semantic matching (opt-in) + shared embedding config

Phase 3 — skills:
Route the skill VectorMatcher through internal/embedding. The skill corpus
embeds once at reload (cheap); only the query embeds per turn, so the HTTP
backend is opt-in and time-bounded:
  - NewVectorMatcherWithConfig selects the backend; default stays local RP.
  - For an HTTP config that omits timeout_seconds, a short 2s query timeout is
    applied so the per-turn embed fails fast.
  - SkillManager.MatchLazySkills is the single entry point the agent loop wires:
    when a remote backend is configured it tries semantic matching first and
    falls back to the keyword ScoredMatcher on no-match/timeout/down-backend;
    otherwise it uses the keyword matcher directly (unchanged default). The
    local RP vector matcher stays a fallback, never the primary.

Phase 4 — shared config + docs:
  - New top-level `embedding` block is the shared default. Memory inherits it
    unless memory.embedding overrides (back-compat); sessions read it for
    semantic session_search; skills do NOT inherit it — opt in via
    skills.embedding because they run on every turn.
  - Resolved into ResolvedConfig.Embedding and Skills.Embedding; merge + memory
    inheritance wired in the loader.
  - Session init and the skill managers across all agent entry points (run,
    continue, repl, serve, subagent, mcp, telegram) now take the resolved
    embedding configs.
  - CONFIG.md documents the shared backend, the inherit/opt-in matrix, and the
    per-subsystem resilience (session fingerprint rebuild, skill fail-fast
    fallback, egress warning).

Tests: HTTP-backed semantic skill match, default-RP-not-semantic, keyword
fallback when the skills backend is down, and config resolution for top-level
inheritance + per-subsystem overrides.

Author: claude

cmd/odek/main.go

@@ -828,9 +828,10 @@ func run(args []string) error {
 	// Skills setup
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 
@@ -1657,9 +1658,9 @@ func continueCmd(args []string) error {
 	// Resolve config (no CLI flags for continue — uses session's model)
 	resolved := config.LoadConfig(config.CLIFlags{Model: sess.Model})
 
-	// Initialize semantic search index (non-fatal on failure). Sessions share
-	// memory's embedding backend so one endpoint config powers both.
-	_ = store.InitVectorIndex(resolved.Memory.Embedding)
+	// Initialize semantic search index (non-fatal on failure). Sessions use the
+	// shared top-level embedding backend.
+	_ = store.InitVectorIndex(resolved.Embedding)
 
 	// Auto-apply sandbox if session was sandboxed (even if config changed)
 	if sess.Sandbox && !resolved.Sandbox {
@@ -1670,9 +1671,10 @@ func continueCmd(args []string) error {
 	// Build tools
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, store)

cmd/odek/mcp.go

@@ -66,9 +66,10 @@ Flags:
 	// Build skills manager (for skill tools)
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 

cmd/odek/repl.go

@@ -72,9 +72,10 @@ func replCmd(args []string) error {
 	// Build tools
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)

cmd/odek/serve.go

@@ -257,9 +257,10 @@ func serveOnListener(listener net.Listener, mux *http.ServeMux) error {
 func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v any) error) (*odek.Agent, func() error, func(), *wsApprover, error) {
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 

cmd/odek/subagent.go

@@ -286,9 +286,10 @@ func subagentCmd(args []string) error {
 	// Build tools
 	var sm *skills.SkillManager
 	if resolved.Skills.Learn {
-		sm = skills.NewSkillManager(
+		sm = skills.NewSkillManagerWithEmbedding(
 			expandHome("~/.odek/skills"),
 			"./.odek/skills",
+			resolved.Skills.Embedding,
 		)
 	}
 	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)

cmd/odek/telegram.go

@@ -143,9 +143,9 @@ func telegramCmd(args []string) error {
 		return err
 	}
 
-	// Initialize semantic search index. Sessions share memory's embedding
-	// backend so a single Ollama/OpenAI endpoint config powers both.
-	if err := store.InitVectorIndex(resolved.Memory.Embedding); err != nil {
+	// Initialize semantic search index using the shared top-level embedding
+	// backend so a single Ollama/OpenAI endpoint config powers it.
+	if err := store.InitVectorIndex(resolved.Embedding); err != nil {
 		fmt.Fprintf(os.Stderr, "odek telegram: vector index: %v\n", err)
 		// Non-fatal — search falls back to metadata-only.
 	}

docs/CONFIG.md

@@ -282,6 +282,64 @@ Operational notes:
   (e.g. cloud metadata services) you would not otherwise expose. Prefer a local
   server (Ollama/llama.cpp) when episode/fact text must not leave the machine.
 
+## Shared embedding backend (`embedding`) — sessions & skills
+
+The same embedder that powers memory also powers **semantic session search**
+(the `session_search` tool) and, opt-in, **semantic skill matching**. Rather
+than configuring three separate endpoints, set one **top-level `embedding`
+block** as the shared default; subsystems then inherit or override it. The block
+uses the exact same fields as `memory.embedding` above
+(`provider`/`base_url`/`model`/`api_key`/`dims`/`timeout_seconds`).
+
+```json
+{
+  "embedding": {
+    "provider": "http",
+    "base_url": "http://localhost:11434/v1",
+    "model": "nomic-embed-text"
+  }
+}
+```
+
+| Subsystem | Uses the shared `embedding`? | Override |
+|-----------|------------------------------|----------|
+| **Memory** | Yes, when `memory.embedding` is unset | `memory.embedding` wins if set (back-compat) |
+| **Sessions** (`session_search`) | Yes — semantic session search | *(top-level only)* |
+| **Skills** (lazy matching) | **No — opt-in** | `skills.embedding` (explicit) |
+
+Why skills are opt-in: skill matching runs on **every user turn**, so a remote
+embedding call sits on the hot path. Sessions and memory embed infrequently
+(explicit search / session-end) and persist their vectors, so inheriting the
+shared default there is cheap. To enable semantic skill matching, set
+`skills.embedding` explicitly:
+
+```json
+{
+  "skills": {
+    "embedding": {
+      "provider": "http",
+      "base_url": "http://localhost:11434/v1",
+      "model": "nomic-embed-text",
+      "timeout_seconds": 2
+    }
+  }
+}
+```
+
+Operational notes:
+
+- **Sessions self-heal across backend changes** exactly like memory: a
+  `vectors_meta.json` fingerprint records the embedding space; changing
+  `provider`/`model`/`dims` forces a one-time rebuild from the session files. A
+  down backend degrades `session_search` to its keyword fallback and backs off
+  for 30s — it never fails a session save.
+- **Skill matching fails fast and falls back.** The per-turn query embed is
+  bounded by a short timeout (defaults to 2s when `skills.embedding` omits
+  `timeout_seconds`); on a slow/failed/empty result the matcher falls back to
+  the local keyword matcher, so a down backend never stalls or blocks loading.
+- The **egress warning above applies to every subsystem** — session transcripts
+  and skill text are POSTed to `base_url`. Point it only at a server you trust.
+
 ### ⚠️ `extract_facts` — automatic fact learning (opt-in, off by default)
 
 When enabled, after each session of ≥3 turns odek asks the LLM to pull a few

internal/config/loader.go

@@ -22,6 +22,7 @@ import (
 	"strings"
 
 	"github.com/BackendStack21/odek/internal/danger"
+	"github.com/BackendStack21/odek/internal/embedding"
 	"github.com/BackendStack21/odek/internal/mcpclient"
 	"github.com/BackendStack21/odek/internal/memory"
 	"github.com/BackendStack21/odek/internal/redact"
@@ -85,6 +86,7 @@ type SkillsConfig struct {
 	LLMLearn     *bool                  `json:"llm_learn,omitempty"`
 	LLMCurate    *bool                  `json:"llm_curate,omitempty"`
 	Verbose      *bool                  `json:"verbose,omitempty"`
+	Embedding    *embedding.Config      `json:"embedding,omitempty"`
 }
 
 // TranscriptionConfig controls the transcribe tool (local whisper.cpp).
@@ -175,6 +177,12 @@ type FileConfig struct {
 	// Memory section controls the persistent memory system.
 	Memory *memory.MemoryConfig `json:"memory,omitempty"`
 
+	// Embedding is the shared default embedding backend for semantic retrieval.
+	// Memory uses it unless memory.embedding overrides it, and sessions use it
+	// for semantic session_search. Skills opt in separately (skills.embedding)
+	// because they run on every turn. See internal/embedding.Config.
+	Embedding *embedding.Config `json:"embedding,omitempty"`
+
 	// MCPServers maps server names to MCP server configurations.
 	// Each server is an external MCP server (e.g., Playwright, database,
 	// web scraping) whose tools are exposed to the agent.
@@ -297,6 +305,11 @@ type ResolvedConfig struct {
 	// Memory is the resolved memory config with default values.
 	Memory memory.MemoryConfig
 
+	// Embedding is the resolved shared embedding backend used by sessions for
+	// semantic session_search (and as memory's default when memory.embedding is
+	// unset). nil = default RandomProjections.
+	Embedding *embedding.Config
+
 	// MCPServers maps server names to external MCP server configurations.
 	// Populated from the mcp_servers section of odek.json.
 	MCPServers map[string]mcpclient.ServerConfig
@@ -713,6 +726,7 @@ func LoadConfig(cli CLIFlags) ResolvedConfig {
 		Skills:          resolveSkills(cfg.Skills),
 		Dangerous:       resolveDangerous(cfg.Dangerous),
 		Memory:          resolveMemory(cfg.Memory),
+		Embedding:       cfg.Embedding,
 		MCPServers:      cfg.MCPServers,
 		Telegram:        resolveTelegram(cfg.Telegram),
 		Transcription:   resolveTranscription(cfg.Transcription),
@@ -723,6 +737,13 @@ func LoadConfig(cli CLIFlags) ResolvedConfig {
 		ToolProgress:    ifZero(cfg.ToolProgress, "all"),
 	}
 
+	// Memory inherits the shared top-level embedding backend unless it set its
+	// own (memory.embedding wins for back-compat). Sessions read
+	// resolved.Embedding directly; skills opt in via skills.embedding only.
+	if resolved.Memory.Embedding == nil {
+		resolved.Memory.Embedding = cfg.Embedding
+	}
+
 	// MaxConcurrency: default to 3 if not set
 	if cfg.MaxConcurrency > 0 {
 		resolved.MaxConcurrency = cfg.MaxConcurrency
@@ -846,6 +867,10 @@ func resolveSkills(cfg *SkillsConfig) skills.SkillsConfig {
 	if cfg.Verbose != nil {
 		def.Verbose = *cfg.Verbose
 	}
+	// Opt-in only: skills do not inherit the top-level embedding default.
+	if cfg.Embedding != nil {
+		def.Embedding = cfg.Embedding
+	}
 	return def
 }
 
@@ -1149,6 +1174,9 @@ func overlayFile(base, override FileConfig) FileConfig {
 	if override.Memory != nil {
 		base.Memory = override.Memory
 	}
+	if override.Embedding != nil {
+		base.Embedding = override.Embedding
+	}
 	if override.Telegram != nil {
 		base.Telegram = override.Telegram
 	}

internal/config/loader_test.go

@@ -935,3 +935,61 @@ func TestLoadConfig_MemoryEmbeddingSection(t *testing.T) {
 		t.Errorf("base_url/api_key = %q/%q, want unexpanded ${...} placeholders", emb.BaseURL, emb.APIKey)
 	}
 }
+
+// TestLoadConfig_TopLevelEmbeddingShared verifies the shared top-level
+// embedding block: it populates ResolvedConfig.Embedding (sessions read it) and
+// memory inherits it when memory.embedding is unset. Skills do NOT inherit it —
+// skill matching is opt-in via skills.embedding only.
+func TestLoadConfig_TopLevelEmbeddingShared(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	t.Chdir(dir)
+	if err := os.WriteFile(filepath.Join(dir, "odek.json"), []byte(`{
+		"embedding": {
+			"provider": "http",
+			"base_url": "http://localhost:11434/v1",
+			"model": "nomic-embed-text"
+		}
+	}`), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cfg := LoadConfig(CLIFlags{})
+
+	if cfg.Embedding == nil || cfg.Embedding.Model != "nomic-embed-text" {
+		t.Fatalf("top-level embedding not resolved: %+v", cfg.Embedding)
+	}
+	// Memory inherits the shared default.
+	if cfg.Memory.Embedding == nil || cfg.Memory.Embedding.Model != "nomic-embed-text" {
+		t.Errorf("memory should inherit top-level embedding, got %+v", cfg.Memory.Embedding)
+	}
+	// Skills do NOT inherit it (opt-in only).
+	if cfg.Skills.Embedding != nil {
+		t.Errorf("skills must not inherit the top-level embedding default, got %+v", cfg.Skills.Embedding)
+	}
+}
+
+// TestLoadConfig_EmbeddingOverrides verifies memory.embedding overrides the
+// shared default and skills.embedding opts in independently.
+func TestLoadConfig_EmbeddingOverrides(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	t.Chdir(dir)
+	if err := os.WriteFile(filepath.Join(dir, "odek.json"), []byte(`{
+		"embedding": {"provider": "http", "base_url": "http://shared/v1", "model": "shared-model"},
+		"memory": {"embedding": {"provider": "http", "base_url": "http://mem/v1", "model": "mem-model"}},
+		"skills": {"embedding": {"provider": "http", "base_url": "http://skill/v1", "model": "skill-model"}}
+	}`), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cfg := LoadConfig(CLIFlags{})
+
+	if cfg.Embedding == nil || cfg.Embedding.Model != "shared-model" {
+		t.Fatalf("shared embedding = %+v, want shared-model", cfg.Embedding)
+	}
+	if cfg.Memory.Embedding == nil || cfg.Memory.Embedding.Model != "mem-model" {
+		t.Errorf("memory.embedding should win over shared default, got %+v", cfg.Memory.Embedding)
+	}
+	if cfg.Skills.Embedding == nil || cfg.Skills.Embedding.Model != "skill-model" {
+		t.Errorf("skills.embedding opt-in = %+v, want skill-model", cfg.Skills.Embedding)
+	}
+}