fix: remove duplicate else block in workflow-prepare.sh

Remove ~170MB of model files from the repository (LFS + committed).
Models are now downloaded at runtime from Hugging Face on first use
and cached to the OS cache directory with progress reporting and retries.

- Add internal/models/download.go: runtime downloader with retry, progress bar, checksums
- Remove go:embed for ONNX models (keep tokenizers embedded)
- Use file-based ONNX session loading instead of byte-slice
- Add scripts/download-models.sh for dev/CI model setup
- Update Makefile with setup-models target
- Update workflow-prepare.sh to download models in CI
- Set lfs: false in all CI workflows
- SHA256: bge=828e14..., cross-encoder=5d3e70...

.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "claude-mnemonic",
+  "version": "0.6.38",
+  "description": "Persistent memory system for Claude Code - stores observations, session summaries, and user prompts with semantic search",
+  "owner": {
+    "name": "lukaszraczylo",
+    "email": "[email protected]"
+  },
+  "plugins": [
+    {
+      "name": "claude-mnemonic",
+      "description": "Persistent memory system for Claude Code - Go implementation with SQLite and ChromaDB",
+      "version": "0.6.38",
+      "author": {
+        "name": "lukaszraczylo"
+      },
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "claude-mnemonic",
+  "version": "v0.11.57-dirty",
+  "description": "Persistent memory system for Claude Code with SQLite, FTS5, and vector search",
+  "author": {
+    "name": "lukaszraczylo",
+    "email": "[email protected]",
+    "url": "https://github.com/lukaszraczylo"
+  },
+  "homepage": "https://github.com/lukaszraczylo/claude-mnemonic",
+  "repository": "https://github.com/lukaszraczylo/claude-mnemonic",
+  "license": "MIT",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": {
+    "claude-mnemonic": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-server",
+      "args": ["--project", "${CLAUDE_PROJECT}"],
+      "env": {}
+    }
+  },
+  "commands": ["./commands/restart.md"]
+}

.gitattributes

@@ -1 +1,2 @@
-internal/embedding/assets/*.onnx filter=lfs diff=lfs merge=lfs -text
+# Models are now downloaded at runtime from GitHub Releases.
+# LFS tracking removed. See internal/models/download.go

.github/workflows/autoupdate.yaml

@@ -17,5 +17,5 @@ jobs:
     with:
       go-version: ">=1.24"
       release-workflow: "release.yaml"
-      lfs: true
+      lfs: false
     secrets: inherit

.github/workflows/ci.yaml

@@ -20,6 +20,6 @@ jobs:
     uses: lukaszraczylo/shared-actions/.github/workflows/go-pr.yaml@main
     with:
       go-version: ">=1.24"
-      lfs: true
+      lfs: false
       build-tags: "fts5"
     secrets: inherit

.github/workflows/release.yaml

@@ -25,7 +25,7 @@ jobs:
             node-cache-dependency-path: "ui/package-lock.json"
             node-output-path: "ui/dist"
             node-embed-path: "internal/worker/static"
-            lfs: true
+            lfs: false
         secrets: inherit
 
     commit-marketplace:

.gitignore

@@ -1,5 +1,7 @@
 # Binaries
 bin/
+/mcp
+/worker
 *.exe
 *.exe~
 *.dll
@@ -79,14 +81,17 @@ logs/
 *.db-wal
 *.db-shm
 
+# Model files (downloaded at runtime from GitHub Releases)
+# Test model data (downloaded from Hugging Face)
+testdata/models/
+internal/embedding/assets/model.onnx
+internal/reranking/assets/model.onnx
+
 # goreleaser
 dist/
 docs/dist
-.claude-plugin
 
-# Auto-generated plugin configs (generated by scripts/generate-plugin-config.sh)
-.claude-plugin/
-
-# Non-template plugin configs (keep only .tpl files)
+# Non-template plugin configs (keep only .tpl files in plugin/ dir)
 plugin/.claude-plugin/plugin.json
 plugin/.claude-plugin/marketplace.json
+user-prompt

Makefile

@@ -5,6 +5,7 @@ VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev
 LDFLAGS := -ldflags "-X main.Version=$(VERSION) -X github.com/lukaszraczylo/claude-mnemonic/pkg/hooks.Version=$(VERSION) -s -w" -buildvcs=false
 BUILD_DIR := bin
 PLUGIN_DIR := plugin
+STABLE_BIN := $(HOME)/.claude-mnemonic/bin
 
 # Go settings
 GOOS ?= $(shell go env GOOS)
@@ -14,7 +15,7 @@ GOARCH ?= $(shell go env GOARCH)
 export CGO_ENABLED=1
 BUILD_TAGS := -tags "fts5"
 
-.PHONY: all build clean test install lint hooks worker mcp stop-worker start-worker restart-worker dashboard website dev-website setup-libs
+.PHONY: all build clean test install lint hooks worker mcp stop-worker start-worker restart-worker dashboard website dev-website setup-libs update-version
 
 all: build
 
@@ -22,8 +23,23 @@ all: build
 setup-libs:
 	@./scripts/download-onnx-libs.sh all
 
+# Download ONNX models from Hugging Face (for local dev, skips if present)
+setup-models:
+	@./scripts/download-models.sh
+
+# Update version in committed plugin metadata
+update-version:
+	@if [ -f .claude-plugin/plugin.json ]; then \
+		sed 's/"version": "[^"]*"/"version": "$(VERSION)"/' .claude-plugin/plugin.json > .claude-plugin/plugin.json.tmp && mv .claude-plugin/plugin.json.tmp .claude-plugin/plugin.json; \
+		echo "Updated .claude-plugin/plugin.json to version $(VERSION)"; \
+	fi
+	@if [ -f marketplace.json ]; then \
+		sed 's/"version": "[^"]*"/"version": "$(VERSION)"/' marketplace.json > marketplace.json.tmp && mv marketplace.json.tmp marketplace.json; \
+		echo "Updated marketplace.json version fields to $(VERSION)"; \
+	fi
+
 # Build all binaries
-build: setup-libs dashboard worker hooks mcp
+build: setup-libs update-version dashboard worker hooks mcp
 
 # Build Vue dashboard
 dashboard:
@@ -108,7 +124,12 @@ build-windows:
 # Stop any running worker
 stop-worker:
 	@echo "Stopping worker..."
+	@-pkill -TERM -f 'claude-mnemonic.*worker' 2>/dev/null || true
+	@-pkill -TERM -f '\.claude-mnemonic/bin/worker' 2>/dev/null || true
+	@-pkill -TERM -f '\.claude/plugins/.*/worker' 2>/dev/null || true
+	@sleep 1
 	@-pkill -9 -f 'claude-mnemonic.*worker' 2>/dev/null || true
+	@-pkill -9 -f '\.claude-mnemonic/bin/worker' 2>/dev/null || true
 	@-pkill -9 -f '\.claude/plugins/.*/worker' 2>/dev/null || true
 	@-lsof -ti :37777 | xargs kill -9 2>/dev/null || true
 	@sleep 1
@@ -116,12 +137,7 @@ stop-worker:
 # Start worker in background
 start-worker:
 	@echo "Starting worker..."
-	@# Prefer cache directory (where Claude Code looks), fall back to marketplaces
-	@if [ -f "$(HOME)/.claude/plugins/cache/claude-mnemonic/claude-mnemonic/$(VERSION)/worker" ]; then \
-		nohup $(HOME)/.claude/plugins/cache/claude-mnemonic/claude-mnemonic/$(VERSION)/worker > /tmp/claude-mnemonic-worker.log 2>&1 & \
-	else \
-		nohup $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/worker > /tmp/claude-mnemonic-worker.log 2>&1 & \
-	fi
+	@nohup $(STABLE_BIN)/worker > /tmp/claude-mnemonic-worker.log 2>&1 &
 	@sleep 1
 	@if curl -s http://localhost:37777/health > /dev/null 2>&1; then \
 		echo "Worker started successfully (http://localhost:37777)"; \
@@ -132,22 +148,31 @@ start-worker:
 # Restart worker
 restart-worker: stop-worker start-worker
 
-# Install to Claude plugins directory
+# Install to stable binary location and register with Claude Code
 install: build stop-worker
-	@echo "Installing to Claude plugins directory..."
-	@# Install to marketplaces directory (for direct installs)
-	@mkdir -p $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks
+	@echo "Installing claude-mnemonic..."
+	@# Verify build output binaries exist
+	@test -f $(BUILD_DIR)/worker || { echo "ERROR: $(BUILD_DIR)/worker not found. Build may have failed."; exit 1; }
+	@test -f $(BUILD_DIR)/mcp-server || { echo "ERROR: $(BUILD_DIR)/mcp-server not found. Build may have failed."; exit 1; }
+	@test -d $(BUILD_DIR)/hooks || { echo "ERROR: $(BUILD_DIR)/hooks not found. Build may have failed."; exit 1; }
+	@# Install binaries to stable location (survives Claude Code updates)
+	@mkdir -p $(STABLE_BIN)/hooks
+	cp $(BUILD_DIR)/worker $(STABLE_BIN)/
+	cp $(BUILD_DIR)/mcp-server $(STABLE_BIN)/
+	cp $(BUILD_DIR)/hooks/* $(STABLE_BIN)/hooks/
+	@echo "Binaries installed to $(STABLE_BIN)"
+	@# Set up marketplace directory with wrapper scripts and metadata
 	@mkdir -p $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/.claude-plugin
+	@mkdir -p $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks
 	@mkdir -p $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/commands
-	cp $(BUILD_DIR)/worker $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/
-	cp $(BUILD_DIR)/mcp-server $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/
-	cp $(BUILD_DIR)/hooks/* $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks/
-	cp $(PLUGIN_DIR)/hooks/hooks.json $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks/
-	@# Copy slash commands if they exist
-	@if [ -d "$(PLUGIN_DIR)/commands" ]; then cp -r $(PLUGIN_DIR)/commands/* $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/commands/ 2>/dev/null || true; fi
-	@# Update plugin.json and marketplace.json with current version to prevent stale version directories
-	@sed 's/{{ .Version }}/$(VERSION)/g; s/{{.Version}}/$(VERSION)/g' $(PLUGIN_DIR)/.claude-plugin/plugin.json.tpl > $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/.claude-plugin/plugin.json
-	@sed 's/{{ .Version }}/$(VERSION)/g; s/{{.Version}}/$(VERSION)/g' $(PLUGIN_DIR)/.claude-plugin/marketplace.json.tpl > $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/.claude-plugin/marketplace.json
+	@cp .claude-plugin/plugin.json $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/.claude-plugin/
+	@cp marketplace.json $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/.claude-plugin/marketplace.json 2>/dev/null || true
+	@cp hooks/hooks.json $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks/
+	@cp hooks/session-start hooks/user-prompt hooks/post-tool-use hooks/stop hooks/subagent-stop hooks/statusline $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks/
+	@chmod +x $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/hooks/*
+	@cp mcp-server $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/
+	@chmod +x $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/mcp-server
+	@cp commands/restart.md $(HOME)/.claude/plugins/marketplaces/claude-mnemonic/commands/
 	@echo "Registering plugin with Claude Code..."
 	@./scripts/register-plugin.sh "$(VERSION)"
 	@$(MAKE) start-worker
@@ -161,12 +186,14 @@ uninstall: stop-worker
 	@echo "Uninstallation complete!"
 
 # Run tests (with FTS5 support)
-test: setup-libs
-	go test $(BUILD_TAGS) -v -race ./...
+# CLAUDE_MNEMONIC_MODEL_DIR points to a common model directory for tests.
+# Run setup-models first to download models from Hugging Face.
+test: setup-libs setup-models
+	CLAUDE_MNEMONIC_MODEL_DIR=$$(pwd)/testdata/models go test $(BUILD_TAGS) -v -race ./...
 
 # Run tests with coverage (with FTS5 support)
-test-coverage: setup-libs
-	go test $(BUILD_TAGS) -v -race -coverprofile=coverage.out ./...
+test-coverage: setup-libs setup-models
+	CLAUDE_MNEMONIC_MODEL_DIR=$$(pwd)/testdata/models go test $(BUILD_TAGS) -v -race -coverprofile=coverage.out ./...
 	go tool cover -html=coverage.out -o coverage.html
 	@go tool cover -func=coverage.out | tail -1
 
@@ -228,6 +255,7 @@ help:
 	@echo "  make fmt            - Format code"
 	@echo "  make clean          - Clean build artifacts"
 	@echo "  make dev            - Run worker in development mode"
+	@echo "  make update-version - Update version in plugin metadata files"
 	@echo "  make deps           - Download dependencies"
 	@echo "  make website        - Build website for production"
 	@echo "  make dev-website    - Run website dev server"

cmd/hooks/post-tool-use/main.go

@@ -2,8 +2,10 @@
 package main
 
 import (
+	"context"
 	"fmt"
 	"os"
+	"time"
 
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/hooks"
 )
@@ -51,6 +53,10 @@ var skipTools = map[string]bool{
 }
 
 func main() {
+	if !hooks.IsWorkerAvailable() {
+		hooks.WriteResponse("PostToolUse", true)
+		return
+	}
 	hooks.RunHook("PostToolUse", handlePostToolUse)
 }
 
@@ -63,15 +69,31 @@ func handlePostToolUse(ctx *hooks.HookContext, input *Input) (string, error) {
 
 	fmt.Fprintf(os.Stderr, "[post-tool-use] %s\n", input.ToolName)
 
-	// Send observation to worker
-	_, err := hooks.POST(ctx.Port, "/api/sessions/observations", map[string]interface{}{
-		"claudeSessionId": ctx.SessionID,
-		"project":         ctx.Project,
-		"tool_name":       input.ToolName,
-		"tool_input":      input.ToolInput,
-		"tool_response":   input.ToolResponse,
-		"cwd":             ctx.CWD,
-	})
+	// Fire-and-forget: send the observation without waiting for the response.
+	// The worker just queues it -- we don't need the response data.
+	// Use a short-lived context to ensure the request body is at least sent
+	// before this process exits.
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		sendCtx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+		defer cancel()
+		_ = hooks.POSTWithContext(sendCtx, ctx.Port, "/api/sessions/observations", map[string]interface{}{
+			"claudeSessionId": ctx.SessionID,
+			"project":         ctx.Project,
+			"tool_name":       input.ToolName,
+			"tool_input":      input.ToolInput,
+			"tool_response":   input.ToolResponse,
+			"cwd":             ctx.CWD,
+		})
+	}()
 
-	return "", err
+	// Wait briefly for the TCP connection to be established and request sent,
+	// but don't block the hook for the full response.
+	select {
+	case <-done:
+	case <-time.After(100 * time.Millisecond):
+	}
+
+	return "", nil
 }

cmd/hooks/session-start/main.go

@@ -6,6 +6,7 @@ import (
 	"net/url"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/hooks"
 )
@@ -27,10 +28,17 @@ type Observation struct {
 }
 
 func main() {
+	if !hooks.IsWorkerAvailable() {
+		hooks.WriteResponse("SessionStart", true)
+		return
+	}
 	hooks.RunHook("SessionStart", handleSessionStart)
 }
 
 func handleSessionStart(ctx *hooks.HookContext, input *Input) (string, error) {
+	deadline, cancel := hooks.HookDeadline(30 * time.Second)
+	defer cancel()
+
 	// Fetch observations for context injection
 	endpoint := fmt.Sprintf("/api/context/inject?project=%s&cwd=%s",
 		url.QueryEscape(ctx.Project),
@@ -59,12 +67,21 @@ func handleSessionStart(ctx *hooks.HookContext, input *Input) (string, error) {
 	fmt.Fprintf(os.Stderr, "[claude-mnemonic] Injecting %d observations from project memory (%d detailed, %d condensed)\n",
 		len(obsData), min(fullCount, len(obsData)), max(0, len(obsData)-fullCount))
 
+	// Token budget for context injection
+	maxTokens := 16000 // default; could be made configurable via worker config endpoint
+	currentTokens := 0
+
 	// Build context string
-	contextBuilder := "<claude-mnemonic-context>\n"
-	contextBuilder += fmt.Sprintf("# Project Memory (%d observations)\n", len(obsData))
-	contextBuilder += "Use this knowledge to answer questions without re-exploring the codebase.\n\n"
+	header := fmt.Sprintf("<claude-mnemonic-context>\n# Project Memory (%d observations)\nUse this knowledge to answer questions without re-exploring the codebase.\n\n", len(obsData))
+	currentTokens += estimateTokens(header)
+	contextBuilder := header
 
 	for i, o := range obsData {
+		if deadline.Err() != nil {
+			contextBuilder += "\n... (returning early due to time limit)\n"
+			break
+		}
+
 		obs, ok := o.(map[string]interface{})
 		if !ok {
 			continue
@@ -73,40 +90,94 @@ func handleSessionStart(ctx *hooks.HookContext, input *Input) (string, error) {
 		title := getString(obs, "title")
 		obsType := getString(obs, "type")
 
+		var obsText string
+
 		// First `fullCount` observations get full detail, rest are condensed
 		if i < fullCount {
 			// Full detail: include narrative and facts
 			narrative := getString(obs, "narrative")
 
-			contextBuilder += fmt.Sprintf("## %d. [%s] %s\n", i+1, strings.ToUpper(obsType), title)
+			obsText = fmt.Sprintf("## %d. [%s] %s\n", i+1, strings.ToUpper(obsType), title)
 			if narrative != "" {
-				contextBuilder += narrative + "\n"
+				obsText += narrative + "\n"
 			}
 
 			if facts, ok := obs["facts"].([]interface{}); ok && len(facts) > 0 {
-				contextBuilder += "Key facts:\n"
+				obsText += "Key facts:\n"
 				for _, f := range facts {
 					if fact, ok := f.(string); ok && fact != "" {
-						contextBuilder += fmt.Sprintf("- %s\n", fact)
+						obsText += fmt.Sprintf("- %s\n", fact)
 					}
 				}
 			}
-			contextBuilder += "\n"
+			obsText += "\n"
 		} else {
 			// Condensed: just title and subtitle (one line)
 			subtitle := getString(obs, "subtitle")
 			if subtitle != "" {
-				contextBuilder += fmt.Sprintf("- [%s] %s: %s\n", strings.ToUpper(obsType), title, subtitle)
+				obsText = fmt.Sprintf("- [%s] %s: %s\n", strings.ToUpper(obsType), title, subtitle)
 			} else {
-				contextBuilder += fmt.Sprintf("- [%s] %s\n", strings.ToUpper(obsType), title)
+				obsText = fmt.Sprintf("- [%s] %s\n", strings.ToUpper(obsType), title)
 			}
 		}
+
+		obsTokens := estimateTokens(obsText)
+		if currentTokens+obsTokens > maxTokens {
+			contextBuilder += fmt.Sprintf("\n... (%d more observations omitted due to token budget)\n", len(obsData)-i)
+			break
+		}
+
+		contextBuilder += obsText
+		currentTokens += obsTokens
 	}
 
 	contextBuilder += "</claude-mnemonic-context>\n"
 	return contextBuilder, nil
 }
 
+// estimateTokens provides a more accurate token count estimate.
+// Uses word count * 1.3 as base, with adjustments for code and non-ASCII.
+func estimateTokens(s string) int {
+	if len(s) == 0 {
+		return 0
+	}
+
+	// Count words (split on whitespace)
+	words := len(strings.Fields(s))
+	if words == 0 {
+		// No whitespace = probably a single token or code blob
+		return (len(s) + 3) / 4
+	}
+
+	// Base estimate: ~1.3 tokens per word for English text
+	estimate := int(float64(words) * 1.3)
+
+	// Detect code-heavy content (high non-alpha ratio)
+	nonAlpha := 0
+	nonASCII := 0
+	for _, r := range s {
+		if r > 127 {
+			nonASCII++
+		} else if !('a' <= r && r <= 'z') && !('A' <= r && r <= 'Z') && !('0' <= r && r <= '9') && r != ' ' {
+			nonAlpha++
+		}
+	}
+
+	totalChars := len(s)
+
+	// Code adjustment: more special chars = more tokens per word
+	if totalChars > 0 && float64(nonAlpha)/float64(totalChars) > 0.15 {
+		estimate = int(float64(estimate) * 1.3)
+	}
+
+	// Non-ASCII adjustment: CJK and other scripts use more tokens
+	if totalChars > 0 && float64(nonASCII)/float64(totalChars) > 0.1 {
+		estimate += nonASCII // Roughly 1 extra token per non-ASCII char
+	}
+
+	return estimate
+}
+
 func getString(m map[string]interface{}, key string) string {
 	if v, ok := m[key].(string); ok {
 		return v

cmd/hooks/statusline/main.go

@@ -117,7 +117,7 @@ func getWorkerStats(port int, project string) *WorkerStats {
 	if err != nil {
 		return nil
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
 		return nil

cmd/hooks/stop/main.go

@@ -5,12 +5,16 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/hooks"
 )
 
+var debug = os.Getenv("CLAUDE_MNEMONIC_DEBUG") != ""
+
 // Input is the hook input from Claude Code.
 type Input struct {
 	hooks.BaseInput
@@ -62,7 +66,19 @@ func parseTranscript(path string) (lastUser, lastAssistant string) {
 	if err != nil {
 		return "", ""
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
+
+	// For large transcripts, seek to the last 256KB for efficiency.
+	// We only need the last user/assistant messages, not the entire history.
+	const tailSize = 256 * 1024
+	info, err := file.Stat()
+	if err == nil && info.Size() > tailSize {
+		if _, seekErr := file.Seek(-tailSize, io.SeekEnd); seekErr == nil {
+			// Discard partial first line after seek
+			discardScanner := bufio.NewScanner(file)
+			discardScanner.Scan()
+		}
+	}
 
 	scanner := bufio.NewScanner(file)
 	// Increase buffer size for large messages
@@ -97,12 +113,20 @@ func parseTranscript(path string) (lastUser, lastAssistant string) {
 }
 
 func main() {
+	if !hooks.IsWorkerAvailable() {
+		hooks.WriteResponse("Stop", true)
+		return
+	}
 	hooks.RunHook("Stop", handleStop)
 }
 
 func handleStop(ctx *hooks.HookContext, input *Input) (string, error) {
-	// Debug: dump raw input
-	fmt.Fprintf(os.Stderr, "[stop] Raw input: %s\n", string(ctx.RawInput))
+	deadline, cancel := hooks.HookDeadline(30 * time.Second)
+	defer cancel()
+
+	if debug {
+		fmt.Fprintf(os.Stderr, "[stop] Raw input: %s\n", string(ctx.RawInput))
+	}
 
 	// Find session
 	result, err := hooks.GET(ctx.Port, fmt.Sprintf("/api/sessions?claudeSessionId=%s", ctx.SessionID))
@@ -122,18 +146,33 @@ func handleStop(ctx *hooks.HookContext, input *Input) (string, error) {
 		lastUser, lastAssistant = parseTranscript(input.TranscriptPath)
 	}
 
-	// Debug: log what we extracted
-	fmt.Fprintf(os.Stderr, "[stop] Transcript path: %s\n", input.TranscriptPath)
-	fmt.Fprintf(os.Stderr, "[stop] Last user message length: %d\n", len(lastUser))
-	fmt.Fprintf(os.Stderr, "[stop] Last assistant message length: %d\n", len(lastAssistant))
-	if len(lastAssistant) > 0 {
-		preview := lastAssistant
-		if len(preview) > 300 {
-			preview = preview[:300] + "..."
+	// Truncate messages to avoid sending excessive data to the worker
+	if len(lastAssistant) > 10000 {
+		lastAssistant = lastAssistant[:10000]
+	}
+	if len(lastUser) > 5000 {
+		lastUser = lastUser[:5000]
+	}
+
+	if debug {
+		fmt.Fprintf(os.Stderr, "[stop] Transcript path: %s\n", input.TranscriptPath)
+		fmt.Fprintf(os.Stderr, "[stop] Last user message length: %d\n", len(lastUser))
+		fmt.Fprintf(os.Stderr, "[stop] Last assistant message length: %d\n", len(lastAssistant))
+		if len(lastAssistant) > 0 {
+			preview := lastAssistant
+			if len(preview) > 300 {
+				preview = preview[:300] + "..."
+			}
+			fmt.Fprintf(os.Stderr, "[stop] Last assistant preview: %s\n", preview)
 		}
-		fmt.Fprintf(os.Stderr, "[stop] Last assistant preview: %s\n", preview)
+		fmt.Fprintf(os.Stderr, "[stop] Requesting summary for session %d (transcript: %v)\n", int64(sessionID), input.TranscriptPath != "")
+	}
+
+	// Check deadline before expensive summary request
+	if deadline.Err() != nil {
+		fmt.Fprintf(os.Stderr, "[stop] Returning early due to time limit\n")
+		return "", nil
 	}
-	fmt.Fprintf(os.Stderr, "[stop] Requesting summary for session %d (transcript: %v)\n", int64(sessionID), input.TranscriptPath != "")
 
 	// Request summary with message context from transcript
 	_, err = hooks.POST(ctx.Port, fmt.Sprintf("/sessions/%d/summarize", int64(sessionID)), map[string]interface{}{

cmd/hooks/subagent-stop/main.go

@@ -16,6 +16,10 @@ type Input struct {
 }
 
 func main() {
+	if !hooks.IsWorkerAvailable() {
+		hooks.WriteResponse("SubagentStop", true)
+		return
+	}
 	hooks.RunHook("SubagentStop", handleSubagentStop)
 }
 

cmd/hooks/user-prompt/main.go

@@ -5,8 +5,12 @@ import (
 	"fmt"
 	"net/url"
 	"os"
+	"strings"
+	"sync"
+	"time"
 
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/hooks"
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/sanitize"
 )
 
 // Input is the hook input from Claude Code.
@@ -15,31 +19,117 @@ type Input struct {
 	Prompt string `json:"prompt"`
 }
 
+// estimateTokens provides a more accurate token count estimate.
+// Uses word count * 1.3 as base, with adjustments for code and non-ASCII.
+func estimateTokens(s string) int {
+	if len(s) == 0 {
+		return 0
+	}
+
+	// Count words (split on whitespace)
+	words := len(strings.Fields(s))
+	if words == 0 {
+		// No whitespace = probably a single token or code blob
+		return (len(s) + 3) / 4
+	}
+
+	// Base estimate: ~1.3 tokens per word for English text
+	estimate := int(float64(words) * 1.3)
+
+	// Detect code-heavy content (high non-alpha ratio)
+	nonAlpha := 0
+	nonASCII := 0
+	for _, r := range s {
+		if r > 127 {
+			nonASCII++
+		} else if !('a' <= r && r <= 'z') && !('A' <= r && r <= 'Z') && !('0' <= r && r <= '9') && r != ' ' {
+			nonAlpha++
+		}
+	}
+
+	totalChars := len(s)
+
+	// Code adjustment: more special chars = more tokens per word
+	if totalChars > 0 && float64(nonAlpha)/float64(totalChars) > 0.15 {
+		estimate = int(float64(estimate) * 1.3)
+	}
+
+	// Non-ASCII adjustment: CJK and other scripts use more tokens
+	if totalChars > 0 && float64(nonASCII)/float64(totalChars) > 0.1 {
+		estimate += nonASCII // Roughly 1 extra token per non-ASCII char
+	}
+
+	return estimate
+}
+
 func main() {
+	if !hooks.IsWorkerAvailable() {
+		hooks.WriteResponse("UserPromptSubmit", true)
+		return
+	}
 	hooks.RunHook("UserPromptSubmit", handleUserPrompt)
 }
 
 func handleUserPrompt(ctx *hooks.HookContext, input *Input) (string, error) {
-	// Search for relevant observations based on the prompt
+	deadline, cancel := hooks.HookDeadline(10 * time.Second)
+	defer cancel()
+
 	searchURL := fmt.Sprintf("/api/context/search?project=%s&query=%s&cwd=%s",
 		url.QueryEscape(ctx.Project),
 		url.QueryEscape(input.Prompt),
 		url.QueryEscape(ctx.CWD))
 
-	var contextToInject string
-	var observationCount int
+	// Run search and session init concurrently.
+	// Session init doesn't strictly depend on search results -- the observation
+	// count passed is approximate (0) and acceptable.
+	var (
+		wg               sync.WaitGroup
+		searchResult     map[string]interface{}
+		initResult       map[string]interface{}
+		initErr          error
+		contextToInject  string
+		observationCount int
+	)
 
-	searchResult, _ := hooks.GET(ctx.Port, searchURL)
+	// Start search in background
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		searchResult, _ = hooks.GET(ctx.Port, searchURL)
+	}()
+
+	// Start session init in parallel (with observationCount=0; approximate is fine)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		initResult, initErr = hooks.POST(ctx.Port, "/api/sessions/init", map[string]interface{}{
+			"claudeSessionId":     ctx.SessionID,
+			"project":             ctx.Project,
+			"prompt":              input.Prompt,
+			"matchedObservations": 0,
+		})
+	}()
+
+	// Wait for both to complete
+	wg.Wait()
+
+	// Check deadline after network calls
+	if deadline.Err() != nil {
+		return "", nil
+	}
+
+	// Process search results
 	if observations, ok := searchResult["observations"].([]interface{}); ok && len(observations) > 0 {
-		// Results are already filtered by relevance threshold and capped by max_results
-		// from the server-side config (ContextRelevanceThreshold, ContextMaxPromptResults)
 		observationCount = len(observations)
 
-		// Build context from search results
+		// Token budget for prompt context injection
+		maxTokens := 8000
+		currentTokens := 0
+
+		header := "<relevant-memory>\n# Relevant Knowledge From Previous Sessions\nIMPORTANT: Use this information to answer the question directly. Do NOT explore the codebase if the answer is here.\n\n"
+		currentTokens += estimateTokens(header)
 		var contextBuilder string
-		contextBuilder = "<relevant-memory>\n"
-		contextBuilder += "# Relevant Knowledge From Previous Sessions\n"
-		contextBuilder += "IMPORTANT: Use this information to answer the question directly. Do NOT explore the codebase if the answer is here.\n\n"
+		contextBuilder = header
 
 		for i, obs := range observations {
 			if obsMap, ok := obs.(map[string]interface{}); ok {
@@ -52,24 +142,30 @@ func handleUserPrompt(ctx *hooks.HookContext, input *Input) (string, error) {
 					obsType = t
 				}
 
-				// Start observation block
-				contextBuilder += fmt.Sprintf("## %d. [%s] %s\n", i+1, obsType, title)
+				var obsText string
+				obsText = fmt.Sprintf("## %d. [%s] %s\n", i+1, obsType, title)
 
-				// Add facts first (most concise answers)
 				if facts, ok := obsMap["facts"].([]interface{}); ok && len(facts) > 0 {
-					contextBuilder += "Key facts:\n"
+					obsText += "Key facts:\n"
 					for _, fact := range facts {
 						if factStr, ok := fact.(string); ok {
-							contextBuilder += fmt.Sprintf("- %s\n", factStr)
+							obsText += fmt.Sprintf("- %s\n", sanitize.StripSystemXML(factStr))
 						}
 					}
-					contextBuilder += "\n"
+					obsText += "\n"
 				}
 
-				// Add narrative if present
 				if narrative, ok := obsMap["narrative"].(string); ok && narrative != "" {
-					contextBuilder += narrative + "\n\n"
+					obsText += sanitize.StripSystemXML(narrative) + "\n\n"
 				}
+
+				obsTokens := estimateTokens(obsText)
+				if currentTokens+obsTokens > maxTokens {
+					break
+				}
+
+				contextBuilder += obsText
+				currentTokens += obsTokens
 			}
 		}
 
@@ -77,40 +173,36 @@ func handleUserPrompt(ctx *hooks.HookContext, input *Input) (string, error) {
 		contextToInject = contextBuilder
 	}
 
-	// Initialize session with matched observations count
-	result, err := hooks.POST(ctx.Port, "/api/sessions/init", map[string]interface{}{
-		"claudeSessionId":     ctx.SessionID,
-		"project":             ctx.Project,
-		"prompt":              input.Prompt,
-		"matchedObservations": observationCount,
-	})
-	if err != nil {
-		return "", err
+	// Check session init result
+	if initErr != nil {
+		return "", initErr
+	}
+	if initResult == nil {
+		return contextToInject, nil // Non-JSON response from worker, skip session init
 	}
 
 	// Check if skipped due to privacy
-	if skipped, ok := result["skipped"].(bool); ok && skipped {
+	if skipped, ok := initResult["skipped"].(bool); ok && skipped {
 		fmt.Fprintf(os.Stderr, "[user-prompt] Session skipped (private)\n")
-		return "", nil
+		return contextToInject, nil
 	}
 
-	// Safely extract session ID and prompt number with type checking
-	sessionDbIdRaw, ok := result["sessionDbId"].(float64)
+	sessionDBIDVal, ok := initResult["sessionDbId"].(float64)
 	if !ok {
-		return "", fmt.Errorf("invalid or missing sessionDbId in response")
+		return contextToInject, nil // Missing or wrong type, skip gracefully
 	}
-	sessionID := int64(sessionDbIdRaw)
+	sessionID := int64(sessionDBIDVal)
 
-	promptNumberRaw, ok := result["promptNumber"].(float64)
+	promptNumberVal, ok := initResult["promptNumber"].(float64)
 	if !ok {
-		return "", fmt.Errorf("invalid or missing promptNumber in response")
+		return contextToInject, nil
 	}
-	promptNumber := int(promptNumberRaw)
+	promptNumber := int(promptNumberVal)
 
 	fmt.Fprintf(os.Stderr, "[user-prompt] Session %d, prompt #%d\n", sessionID, promptNumber)
 
-	// Start SDK agent
-	_, err = hooks.POST(ctx.Port, fmt.Sprintf("/sessions/%d/init", sessionID), map[string]interface{}{
+	// Start SDK agent (depends on session init result, so kept sequential)
+	_, err := hooks.POST(ctx.Port, fmt.Sprintf("/sessions/%d/init", sessionID), map[string]interface{}{
 		"userPrompt":   input.Prompt,
 		"promptNumber": promptNumber,
 	})
@@ -120,7 +212,6 @@ func handleUserPrompt(ctx *hooks.HookContext, input *Input) (string, error) {
 
 	// Return context if we found relevant observations
 	if observationCount > 0 {
-		// Show match count to user via stderr
 		fmt.Fprintf(os.Stderr, "[claude-mnemonic] Found %d relevant memories for this prompt\n", observationCount)
 		return contextToInject, nil
 	}

cmd/hooks/user-prompt/main_test.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestEstimateTokens tests the token estimator.
+func TestEstimateTokens(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		minToken int
+		maxToken int
+	}{
+		{"empty string", "", 0, 0},
+		{"single word", "hello", 1, 3},
+		{"simple sentence", "Hello world this is a test", 5, 15},
+		{"code-heavy", "func() { return x.y.z(); }", 5, 30},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := estimateTokens(tt.input)
+			assert.GreaterOrEqual(t, result, tt.minToken)
+			assert.LessOrEqual(t, result, tt.maxToken)
+		})
+	}
+}
+
+// TestHandleUserPrompt_NilInitResult_Compile verifies that the nil-safety
+// fix in handleUserPrompt compiles correctly. The actual nil dereference
+// was at initResult["sessionDbId"].(float64) when initResult was nil.
+// This test ensures the defensive type assertions are present by exercising
+// the token estimator (the handler requires a live HookContext+worker).
+func TestHandleUserPrompt_NilInitResult_Compile(t *testing.T) {
+	// The real regression test is that `go build ./cmd/hooks/user-prompt/`
+	// succeeds with the nil-safe assertions. We can't easily spin up
+	// a full HookContext here, but we verify the package compiles and
+	// the helper functions are sane.
+	assert.Equal(t, 0, estimateTokens(""))
+	assert.Greater(t, estimateTokens("test input"), 0)
+}

cmd/mcp/main.go

@@ -4,20 +4,17 @@ package main
 import (
 	"context"
 	"flag"
+	"fmt"
+	"net/http"
 	"os"
 	"os/signal"
 	"syscall"
 	"time"
 
 	"github.com/lukaszraczylo/claude-mnemonic/internal/config"
-	"github.com/lukaszraczylo/claude-mnemonic/internal/db/gorm"
-	"github.com/lukaszraczylo/claude-mnemonic/internal/embedding"
 	"github.com/lukaszraczylo/claude-mnemonic/internal/mcp"
-	"github.com/lukaszraczylo/claude-mnemonic/internal/scoring"
-	"github.com/lukaszraczylo/claude-mnemonic/internal/search"
-	"github.com/lukaszraczylo/claude-mnemonic/internal/vector/sqlitevec"
 	"github.com/lukaszraczylo/claude-mnemonic/internal/watcher"
-	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+	"github.com/lukaszraczylo/oss-telemetry"
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
 )
@@ -28,7 +25,6 @@ var Version = "dev"
 func main() {
 	// Parse flags
 	project := flag.String("project", "", "Project name (required)")
-	dataDir := flag.String("data-dir", "", "Data directory (default: ~/.claude-mnemonic)")
 	debug := flag.Bool("debug", false, "Enable debug logging")
 	flag.Parse()
 
@@ -43,23 +39,12 @@ func main() {
 		log.Fatal().Msg("--project is required")
 	}
 
-	// Ensure data directory and settings exist
-	if err := config.EnsureAll(); err != nil {
-		log.Fatal().Err(err).Msg("Failed to ensure data directories")
-	}
+	// Get worker port from config
+	port := config.GetWorkerPort()
+	workerURL := fmt.Sprintf("http://localhost:%d", port)
 
-	// Load config
-	cfg, err := config.Load()
-	if err != nil {
-		log.Warn().Err(err).Msg("Failed to load config, using defaults")
-		cfg = config.Default()
-	}
-
-	// Override data directory if specified
-	dbPath := cfg.DBPath
-	if *dataDir != "" {
-		dbPath = *dataDir + "/claude-mnemonic.db"
-	}
+	// Create HTTP client for worker
+	client := &http.Client{Timeout: 30 * time.Second}
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -73,83 +58,31 @@ func main() {
 		cancel()
 	}()
 
-	// Initialize database store (migrations run automatically)
-	storeCfg := gorm.Config{
-		Path:     dbPath,
-		MaxConns: cfg.MaxConns,
-		// WALMode is enabled automatically by GORM
-	}
-	store, err := gorm.NewStore(storeCfg)
-	if err != nil {
-		log.Fatal().Err(err).Msg("Failed to initialize database store")
-	}
-	defer store.Close()
+	// Start file watchers for config changes
+	startWatchers(cancel)
 
-	// Initialize stores
-	observationStore := gorm.NewObservationStore(store, nil, nil, nil)
-	summaryStore := gorm.NewSummaryStore(store)
-	promptStore := gorm.NewPromptStore(store, nil)
-	patternStore := gorm.NewPatternStore(store)
-	relationStore := gorm.NewRelationStore(store)
-	sessionStore := gorm.NewSessionStore(store)
+	telemetry.Send("claude-mnemonic", Version)
 
-	// Initialize embedding service and vector client
-	var vectorClient *sqlitevec.Client
-	embedSvc, err := embedding.NewService()
-	if err != nil {
-		log.Warn().Err(err).Msg("Embedding service unavailable, vector search disabled")
-	} else {
-		defer embedSvc.Close()
-		vectorClient, err = sqlitevec.NewClient(sqlitevec.Config{DB: store.GetRawDB()}, embedSvc)
-		if err != nil {
-			log.Warn().Err(err).Msg("Vector client unavailable, vector search disabled")
-		} else {
-			log.Info().Msg("Vector search enabled via sqlite-vec")
-		}
-	}
-
-	// Initialize scoring components
-	scoreConfig := models.DefaultScoringConfig()
-	scoreCalculator := scoring.NewCalculator(scoreConfig)
-	recalculator := scoring.NewRecalculator(observationStore, scoreCalculator, log.Logger)
-	go recalculator.Start(ctx)
-	defer recalculator.Stop()
-
-	// Initialize search manager
-	searchMgr := search.NewManager(observationStore, summaryStore, promptStore, vectorClient)
-
-	// Start file watchers
-	startWatchers(ctx, dbPath)
-
-	// Create and run MCP server with all dependencies
-	// Note: maintenanceService is nil because it runs in the worker process
-	server := mcp.NewServer(
-		searchMgr,
-		Version,
-		observationStore,
-		patternStore,
-		relationStore,
-		sessionStore,
-		vectorClient,
-		scoreCalculator,
-		recalculator,
-		nil, // maintenanceService - handled by worker
-	)
-	log.Info().Str("project", *project).Str("version", Version).Msg("Starting MCP server")
+	// Create and run MCP server
+	server := mcp.NewServer(client, workerURL, *project, Version)
+	log.Info().Str("project", *project).Str("version", Version).Str("worker", workerURL).Msg("Starting MCP server")
 
 	if err := server.Run(ctx); err != nil {
+		if err == context.Canceled {
+			log.Info().Msg("MCP server shut down (config change or signal)")
+			return
+		}
 		log.Fatal().Err(err).Msg("MCP server error")
 	}
 }
 
 // startWatchers initializes file watchers for config.
-func startWatchers(ctx context.Context, dbPath string) {
-	// Watch config file for changes (triggers process exit for restart)
+func startWatchers(cancel context.CancelFunc) {
+	// Watch config file for changes (triggers graceful shutdown via context cancellation)
 	configPath := config.SettingsPath()
 	configWatcher, err := watcher.New(configPath, func() {
-		log.Warn().Str("path", configPath).Msg("Config file changed, exiting for restart...")
-		time.Sleep(100 * time.Millisecond) // Give logs time to flush
-		os.Exit(0)
+		log.Warn().Str("path", configPath).Msg("Config file changed, shutting down gracefully...")
+		cancel() // Triggers ctx.Done() in server.Run(), which drains in-flight requests
 	})
 	if err != nil {
 		log.Warn().Err(err).Msg("Failed to create config watcher")

commands/restart.md

@@ -0,0 +1,21 @@
+# Restart Claude Mnemonic Worker
+
+Restart the claude-mnemonic worker process. Use this command when experiencing issues with the memory system.
+
+## Instructions
+
+1. Call the restart API endpoint using curl:
+   ```bash
+   curl -X POST http://127.0.0.1:37777/api/restart
+   ```
+
+2. Wait a moment for the worker to restart (typically 1-2 seconds)
+
+3. Verify the worker is running by checking the version:
+   ```bash
+   curl -s http://127.0.0.1:37777/api/version
+   ```
+
+4. Report the result to the user, including the version number from the response.
+
+If the restart fails, suggest the user check `/tmp/claude-mnemonic-worker.log` for errors.

go.mod

@@ -6,17 +6,18 @@ replace github.com/sugarme/tokenizer => github.com/clems4ever/tokenizer v0.0.0-2
 
 require (
 	github.com/asg017/sqlite-vec-go-bindings v0.1.6
-	github.com/fsnotify/fsnotify v1.9.0
-	github.com/go-chi/chi/v5 v5.2.4
+	github.com/fsnotify/fsnotify v1.10.1
+	github.com/go-chi/chi/v5 v5.3.0
 	github.com/go-gormigrate/gormigrate/v2 v2.1.5
-	github.com/goccy/go-json v0.10.5
-	github.com/mattn/go-sqlite3 v1.14.33
-	github.com/rs/zerolog v1.34.0
+	github.com/goccy/go-json v0.10.6
+	github.com/lukaszraczylo/oss-telemetry v0.2.1
+	github.com/mattn/go-sqlite3 v1.14.44
+	github.com/rs/zerolog v1.35.1
 	github.com/smacker/go-tree-sitter v0.0.0-20240827094217-dd81d9e9be82
 	github.com/stretchr/testify v1.11.1
 	github.com/sugarme/tokenizer v0.3.0
-	github.com/yalue/onnxruntime_go v1.25.0
-	golang.org/x/sync v0.19.0
+	github.com/yalue/onnxruntime_go v1.30.1
+	golang.org/x/sync v0.20.0
 	gorm.io/driver/sqlite v1.6.0
 	gorm.io/gorm v1.31.1
 )
@@ -27,14 +28,14 @@ require (
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-isatty v0.0.22 // indirect
 	github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect
 	github.com/patrickmn/go-cache v2.1.0+incompatible // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/schollz/progressbar/v2 v2.15.0 // indirect
 	github.com/sugarme/regexpset v0.0.0-20200920021344-4d4ec8eaf93c // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/text v0.33.0 // indirect
+	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -2,46 +2,41 @@ github.com/asg017/sqlite-vec-go-bindings v0.1.6 h1:Nx0jAzyS38XpkKznJ9xQjFXz2X9tI
 github.com/asg017/sqlite-vec-go-bindings v0.1.6/go.mod h1:A8+cTt/nKFsYCQF6OgzSNpKZrzNo5gQsXBTfsXHXY0Q=
 github.com/clems4ever/tokenizer v0.0.0-20250926133620-9ddc80533c43 h1:j8YQypEqa5OjqbGciCNb9hOcYbo1oTVuEjd/iu9U2SY=
 github.com/clems4ever/tokenizer v0.0.0-20250926133620-9ddc80533c43/go.mod h1:VJ+DLK5ZEZwzvODOWwY0cw+B1dabTd3nCB5HuFCItCc=
-github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
 github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ=
-github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
-github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/go-chi/chi/v5 v5.2.4 h1:WtFKPHwlywe8Srng8j2BhOD9312j9cGUxG1SP4V2cR4=
-github.com/go-chi/chi/v5 v5.2.4/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
+github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
+github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
 github.com/go-gormigrate/gormigrate/v2 v2.1.5 h1:1OyorA5LtdQw12cyJDEHuTrEV3GiXiIhS4/QTTa/SM8=
 github.com/go-gormigrate/gormigrate/v2 v2.1.5/go.mod h1:mj9ekk/7CPF3VjopaFvWKN2v7fN3D9d3eEOAXRhi/+M=
-github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
-github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
-github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
+github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
 github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
-github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/lukaszraczylo/oss-telemetry v0.2.1 h1:6ULyfzXplpdmIY/i01OPM1jeod9+L1RAhI0jtbVnJI0=
+github.com/lukaszraczylo/oss-telemetry v0.2.1/go.mod h1:+Cn78qZo8rc3T9eZt0v3oICYRdd75wORtSidc8lNjDQ=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
 github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
-github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
-github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-sqlite3 v1.14.33 h1:A5blZ5ulQo2AtayQ9/limgHEkFreKj1Dv226a1K73s0=
-github.com/mattn/go-sqlite3 v1.14.33/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
+github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-sqlite3 v1.14.44 h1:3VSe+xafpbzsLbdr2AWlAZk9yRHiBhTBakioXaCKTF8=
+github.com/mattn/go-sqlite3 v1.14.44/go.mod h1:pjEuOr8IwzLJP2MfGeTb0A35jauH+C2kbHKBr7yXKVQ=
 github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db h1:62I3jR2EmQ4l5rM/4FEfDWcRD+abF5XlKShorW5LRoQ=
 github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db/go.mod h1:l0dey0ia/Uv7NcFFVbCLtqEBQbrT4OCwCSKTEv6enCw=
 github.com/patrickmn/go-cache v2.1.0+incompatible h1:HRMgzkcYKYpi3C8ajMPV8OFXaaRUnok+kx1WdO15EQc=
 github.com/patrickmn/go-cache v2.1.0+incompatible/go.mod h1:3Qf8kWWT7OJRJbdiICTKqZju1ZixQ/KpMGzzAfe6+WQ=
-github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
-github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
-github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
-github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
+github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/schollz/progressbar/v2 v2.15.0 h1:dVzHQ8fHRmtPjD3K10jT3Qgn/+H+92jhPrhmxIJfDz8=
 github.com/schollz/progressbar/v2 v2.15.0/go.mod h1:UdPq3prGkfQ7MOzZKlDRpYKcFqEMczbD7YmbPgpzKMI=
 github.com/smacker/go-tree-sitter v0.0.0-20240827094217-dd81d9e9be82 h1:6C8qej6f1bStuePVkLSFxoU22XBS165D3klxlzRg8F4=
@@ -52,17 +47,14 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/sugarme/regexpset v0.0.0-20200920021344-4d4ec8eaf93c h1:pwb4kNSHb4K89ymCaN+5lPH/MwnfSVg4rzGDh4d+iy4=
 github.com/sugarme/regexpset v0.0.0-20200920021344-4d4ec8eaf93c/go.mod h1:2gwkXLWbDGUQWeL3RtpCmcY4mzCtU13kb9UsAg9xMaw=
-github.com/yalue/onnxruntime_go v1.25.0 h1:nlhVau1BpLZ/BYr+WpPZCJRD/WES0qo6dK7aKyyAs3g=
-github.com/yalue/onnxruntime_go v1.25.0/go.mod h1:b4X26A8pekNb1ACJ58wAXgNKeUCGEAQ9dmACut9Sm/4=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
-golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
+github.com/yalue/onnxruntime_go v1.30.1 h1:NaEng5lWbsHZ/8X1dtaw1mIj7eV1ozyjbFo//g0ktl4=
+github.com/yalue/onnxruntime_go v1.30.1/go.mod h1:b4X26A8pekNb1ACJ58wAXgNKeUCGEAQ9dmACut9Sm/4=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

hooks/hooks.json

@@ -0,0 +1,61 @@
+{
+  "description": "Claude Mnemonic - Persistent memory hooks for observations, prompts, and session summaries",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/post-tool-use

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/post-tool-use"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

hooks/session-start

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/session-start"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

hooks/statusline

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/statusline"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

hooks/stop

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/stop"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

hooks/subagent-stop

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/subagent-stop"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

hooks/user-prompt

@@ -0,0 +1,4 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/hooks/user-prompt"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+exit 0

internal/config/config.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"sync"
 )
@@ -52,6 +53,7 @@ type Config struct {
 	ContextRelevanceThreshold float64  `json:"context_relevance_threshold"`
 	RerankingCandidates       int      `json:"reranking_candidates"`
 	WorkerPort                int      `json:"worker_port"`
+	DeduplicationThreshold    float64  `json:"deduplication_threshold"`
 	RerankingMinImprovement   float64  `json:"reranking_min_improvement"`
 	ContextObservations       int      `json:"context_observations"`
 	ContextMaxPromptResults   int      `json:"context_max_prompt_results"`
@@ -64,10 +66,13 @@ type Config struct {
 	HubThreshold              int      `json:"hub_threshold"`
 	ObservationRetentionDays  int      `json:"observation_retention_days"`
 	MaintenanceIntervalHours  int      `json:"maintenance_interval_hours"`
+	ContextMaxTokensStartup   int      `json:"context_max_tokens_startup"`
+	ContextMaxTokensPrompt    int      `json:"context_max_tokens_prompt"`
 	ContextShowWorkTokens     bool     `json:"context_show_work_tokens"`
 	ContextShowReadTokens     bool     `json:"context_show_read_tokens"`
 	RerankingPureMode         bool     `json:"reranking_pure_mode"`
 	GraphEnabled              bool     `json:"graph_enabled"`
+	DeduplicationEnabled      bool     `json:"deduplication_enabled"`
 	MaintenanceEnabled        bool     `json:"maintenance_enabled"`
 	RerankingEnabled          bool     `json:"reranking_enabled"`
 	ContextShowLastSummary    bool     `json:"context_show_last_summary"`
@@ -168,6 +173,10 @@ func Default() *Config {
 		ContextObsConcepts:        DefaultObservationConcepts,
 		ContextRelevanceThreshold: 0.3,   // Minimum 30% similarity to include
 		ContextMaxPromptResults:   10,    // Cap at 10 results max (0 = no cap, threshold only)
+		ContextMaxTokensStartup:   16000, // Max tokens for SessionStart context injection
+		ContextMaxTokensPrompt:    8000,  // Max tokens for UserPromptSubmit context injection
+		DeduplicationEnabled:      true,  // Enable write-time vector dedup
+		DeduplicationThreshold:    0.9,   // Similarity threshold for merging (0.9 = very similar)
 		MaintenanceEnabled:        true,  // Enable scheduled maintenance
 		MaintenanceIntervalHours:  6,     // Run every 6 hours
 		ObservationRetentionDays:  0,     // 0 = no age-based deletion (keep all)
@@ -269,6 +278,29 @@ func Load() (*Config, error) {
 	if v, ok := settings["CLAUDE_MNEMONIC_HUB_THRESHOLD"].(float64); ok && v > 0 {
 		cfg.HubThreshold = int(v)
 	}
+	if v, ok := settings["CLAUDE_MNEMONIC_CONTEXT_MAX_TOKENS_STARTUP"].(float64); ok && v > 0 {
+		cfg.ContextMaxTokensStartup = int(v)
+	}
+	if v, ok := settings["CLAUDE_MNEMONIC_CONTEXT_MAX_TOKENS_PROMPT"].(float64); ok && v > 0 {
+		cfg.ContextMaxTokensPrompt = int(v)
+	}
+	// Deduplication settings
+	if v, ok := settings["CLAUDE_MNEMONIC_DEDUP_ENABLED"].(bool); ok {
+		cfg.DeduplicationEnabled = v
+	}
+	if v, ok := settings["CLAUDE_MNEMONIC_DEDUP_THRESHOLD"].(float64); ok && v > 0 && v <= 1 {
+		cfg.DeduplicationThreshold = v
+	}
+
+	// Also support env vars for dedup settings
+	if v := os.Getenv("CLAUDE_MNEMONIC_DEDUP_ENABLED"); v != "" {
+		cfg.DeduplicationEnabled = v == "true" || v == "1"
+	}
+	if v := os.Getenv("CLAUDE_MNEMONIC_DEDUP_THRESHOLD"); v != "" {
+		if f, err := strconv.ParseFloat(v, 64); err == nil && f > 0 && f <= 1 {
+			cfg.DeduplicationThreshold = f
+		}
+	}
 
 	return cfg, nil
 }

internal/db/gorm/pattern_store.go

@@ -4,6 +4,8 @@ package gorm
 import (
 	"context"
 	"database/sql"
+	"fmt"
+	"sync"
 	"time"
 
 	"gorm.io/gorm"
@@ -18,6 +20,7 @@ type PatternCleanupFunc func(ctx context.Context, deletedIDs []int64)
 type PatternStore struct {
 	db          *gorm.DB
 	cleanupFunc PatternCleanupFunc
+	cleanupMu   sync.RWMutex
 }
 
 // NewPatternStore creates a new pattern store.
@@ -29,6 +32,8 @@ func NewPatternStore(store *Store) *PatternStore {
 
 // SetCleanupFunc sets the callback for when patterns are deleted.
 func (s *PatternStore) SetCleanupFunc(fn PatternCleanupFunc) {
+	s.cleanupMu.Lock()
+	defer s.cleanupMu.Unlock()
 	s.cleanupFunc = fn
 }
 
@@ -238,6 +243,9 @@ func (s *PatternStore) MarkPatternDeprecated(ctx context.Context, id int64) erro
 
 // MergePatterns merges a source pattern into a target pattern.
 func (s *PatternStore) MergePatterns(ctx context.Context, sourceID, targetID int64) error {
+	if sourceID == targetID {
+		return fmt.Errorf("cannot merge pattern into itself")
+	}
 	// Get both patterns
 	source, err := s.GetPatternByID(ctx, sourceID)
 	if err != nil {
@@ -294,8 +302,13 @@ func (s *PatternStore) MergePatterns(ctx context.Context, sourceID, targetID int
 func (s *PatternStore) DeletePattern(ctx context.Context, id int64) error {
 	result := s.db.WithContext(ctx).Delete(&Pattern{}, id)
 
-	if result.Error == nil && s.cleanupFunc != nil {
-		s.cleanupFunc(ctx, []int64{id})
+	if result.Error == nil {
+		s.cleanupMu.RLock()
+		fn := s.cleanupFunc
+		s.cleanupMu.RUnlock()
+		if fn != nil {
+			fn(ctx, []int64{id})
+		}
 	}
 
 	return result.Error

internal/db/gorm/prompt_store.go

@@ -4,8 +4,10 @@ package gorm
 import (
 	"context"
 	"database/sql"
+	"sync"
 	"time"
 
+	"github.com/rs/zerolog/log"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 
@@ -23,6 +25,7 @@ const MaxPromptsGlobal = 500
 type PromptStore struct {
 	db          *gorm.DB
 	cleanupFunc PromptCleanupFunc
+	cleanupMu   sync.RWMutex
 }
 
 // NewPromptStore creates a new prompt store.
@@ -35,6 +38,8 @@ func NewPromptStore(store *Store, cleanupFunc PromptCleanupFunc) *PromptStore {
 
 // SetCleanupFunc sets the callback for when prompts are deleted during cleanup.
 func (s *PromptStore) SetCleanupFunc(fn PromptCleanupFunc) {
+	s.cleanupMu.Lock()
+	defer s.cleanupMu.Unlock()
 	s.cleanupFunc = fn
 }
 
@@ -81,9 +86,15 @@ func (s *PromptStore) SaveUserPromptWithMatches(ctx context.Context, claudeSessi
 	go func() {
 		cleanupCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 		defer cancel()
-		deletedIDs, _ := s.CleanupOldPrompts(cleanupCtx)
-		if len(deletedIDs) > 0 && s.cleanupFunc != nil {
-			s.cleanupFunc(cleanupCtx, deletedIDs)
+		if deletedIDs, err := s.CleanupOldPrompts(cleanupCtx); err != nil {
+			log.Warn().Err(err).Msg("Background prompt cleanup failed")
+		} else if len(deletedIDs) > 0 {
+			s.cleanupMu.RLock()
+			fn := s.cleanupFunc
+			s.cleanupMu.RUnlock()
+			if fn != nil {
+				fn(cleanupCtx, deletedIDs)
+			}
 		}
 	}()
 
@@ -253,6 +264,28 @@ func (s *PromptStore) FindRecentPromptByText(ctx context.Context, claudeSessionI
 	return prompt.ID, prompt.PromptNumber, true
 }
 
+// FindRecentPromptByTextGlobal finds a recent prompt by exact text match within a time window
+// across ALL sessions (not scoped to a single claude session ID).
+// This catches duplicates when the same prompt arrives from different session IDs,
+// e.g. when the SDK processor's callClaudeCLI subprocess fires with a different session ID.
+// Returns (promptID, promptNumber, found).
+func (s *PromptStore) FindRecentPromptByTextGlobal(ctx context.Context, promptText string, withinSeconds int) (int64, int, bool) {
+	cutoffEpoch := time.Now().Add(-time.Duration(withinSeconds) * time.Second).UnixMilli()
+
+	var prompt UserPrompt
+	err := s.db.WithContext(ctx).
+		Where("prompt_text = ? AND created_at_epoch >= ?",
+			promptText, cutoffEpoch).
+		Order("created_at_epoch DESC").
+		First(&prompt).Error
+
+	if err != nil {
+		return 0, 0, false
+	}
+
+	return prompt.ID, prompt.PromptNumber, true
+}
+
 // GetRecentUserPromptsByProject retrieves recent user prompts for a specific project.
 func (s *PromptStore) GetRecentUserPromptsByProject(ctx context.Context, project string, limit int) ([]*models.UserPromptWithSession, error) {
 	var results []struct {

internal/db/gorm/prompt_store_test.go

@@ -333,6 +333,39 @@ func TestPromptStore_FindRecentPromptByText(t *testing.T) {
 	assert.False(t, notFound, "Should not find prompt outside time window")
 }
 
+func TestPromptStore_FindRecentPromptByTextGlobal(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save a prompt under session "claude-1"
+	id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "What is the architecture?", 3)
+	require.NoError(t, err)
+
+	// Global search should find it without specifying session ID
+	foundID, foundNumber, found := promptStore.FindRecentPromptByTextGlobal(ctx, "What is the architecture?", 60)
+	assert.True(t, found, "Should find the prompt globally")
+	assert.Equal(t, id, foundID)
+	assert.Equal(t, 1, foundNumber)
+
+	// Global search should find it even when a different session ID would have been used
+	// (This is the core cross-session dedup scenario)
+	foundID2, foundNumber2, found2 := promptStore.FindRecentPromptByTextGlobal(ctx, "What is the architecture?", 60)
+	assert.True(t, found2, "Should find the prompt from any session")
+	assert.Equal(t, id, foundID2)
+	assert.Equal(t, 1, foundNumber2)
+
+	// Different text should not match
+	_, _, notFound := promptStore.FindRecentPromptByTextGlobal(ctx, "Different text", 60)
+	assert.False(t, notFound, "Should not find a different prompt")
+
+	// Should not find prompt outside time window
+	time.Sleep(100 * time.Millisecond)
+	_, _, notFound = promptStore.FindRecentPromptByTextGlobal(ctx, "What is the architecture?", 0)
+	assert.False(t, notFound, "Should not find prompt outside time window")
+}
+
 func TestPromptStore_GetRecentUserPromptsByProject(t *testing.T) {
 	promptStore, store, cleanup := testPromptStore(t)
 	defer cleanup()

internal/db/gorm/store.go

@@ -99,8 +99,9 @@ func NewStore(cfg Config) (*Store, error) {
 		"PRAGMA synchronous=NORMAL",
 		"PRAGMA cache_size=-64000",   // 64MB cache (negative = KB)
 		"PRAGMA temp_store=MEMORY",   // Store temp tables in memory
-		"PRAGMA mmap_size=268435456", // 256MB memory-mapped I/O
-		"PRAGMA page_size=4096",      // 4KB pages (optimal for most systems)
+		"PRAGMA mmap_size=268435456",    // 256MB memory-mapped I/O
+		"PRAGMA page_size=4096",         // 4KB pages (optimal for most systems)
+		"PRAGMA wal_autocheckpoint=1000", // Explicit default; checkpoint every 1000 WAL frames
 	}
 	for _, pragma := range pragmas {
 		if _, err := sqlDB.Exec(pragma); err != nil {
@@ -192,6 +193,11 @@ func (s *Store) Optimize(ctx context.Context) error {
 		log.Warn().Err(err).Msg("PRAGMA optimize failed (non-fatal)")
 	}
 
+	// Passive WAL checkpoint — doesn't block readers/writers
+	if _, err := s.sqlDB.ExecContext(ctx, "PRAGMA wal_checkpoint(PASSIVE)"); err != nil {
+		log.Warn().Err(err).Msg("WAL checkpoint failed (non-fatal)")
+	}
+
 	log.Info().Dur("duration", time.Since(start)).Msg("Database optimization complete")
 	return nil
 }
@@ -513,13 +519,6 @@ func (s *Store) ExecWithTimeout(ctx context.Context, timeout time.Duration, quer
 	return nil
 }
 
-// QueryRowWithTimeout executes a row query with timeout.
-func (s *Store) QueryRowWithTimeout(ctx context.Context, timeout time.Duration, query string, args ...any) *sql.Row {
-	timeoutCtx, cancel := s.WithTimeout(ctx, timeout, "query_row")
-	// Note: cancel will be called when row.Scan() completes or errors
-	_ = cancel // Caller must ensure proper cleanup
-	return s.sqlDB.QueryRowContext(timeoutCtx, query, args...)
-}
 
 // TransactionWithTimeout wraps a transaction function with timeout handling.
 // The transaction is automatically rolled back if the context times out.

internal/db/gorm/store_test.go

@@ -4,6 +4,7 @@
 package gorm
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 	"testing"
@@ -150,3 +151,91 @@ func TestMigrationIdempotency(t *testing.T) {
 
 	t.Logf("✅ Migrations are idempotent")
 }
+
+func TestWALAutocheckpoint(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_wal_checkpoint_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	store, err := NewStore(Config{
+		Path:     dbPath,
+		MaxConns: 2,
+		LogLevel: logger.Silent,
+	})
+	if err != nil {
+		t.Fatalf("NewStore failed: %v", err)
+	}
+	defer store.Close()
+
+	// Verify wal_autocheckpoint is set to 1000
+	var checkpoint int
+	err = store.GetRawDB().QueryRow("PRAGMA wal_autocheckpoint").Scan(&checkpoint)
+	if err != nil {
+		t.Fatalf("query wal_autocheckpoint: %v", err)
+	}
+	if checkpoint != 1000 {
+		t.Errorf("expected wal_autocheckpoint=1000, got %d", checkpoint)
+	}
+}
+
+func TestOptimize_RunsWALCheckpoint(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_optimize_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	store, err := NewStore(Config{
+		Path:     dbPath,
+		MaxConns: 2,
+		LogLevel: logger.Silent,
+	})
+	if err != nil {
+		t.Fatalf("NewStore failed: %v", err)
+	}
+	defer store.Close()
+
+	// Insert some data to generate WAL frames
+	_, err = store.GetRawDB().Exec("INSERT INTO observations (sdk_session_id, title, scope, project, type, created_at, created_at_epoch) VALUES ('test-sess', 'test data', 'project', '/tmp/test', 'decision', '2026-01-01T00:00:00Z', 1735689600)")
+	if err != nil {
+		t.Fatalf("insert test data: %v", err)
+	}
+
+	// Optimize should succeed (includes PASSIVE WAL checkpoint)
+	err = store.Optimize(context.Background())
+	if err != nil {
+		t.Fatalf("Optimize failed: %v", err)
+	}
+}
+
+func TestOptimize_RespectsContextCancellation(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_optimize_cancel_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	store, err := NewStore(Config{
+		Path:     dbPath,
+		MaxConns: 2,
+		LogLevel: logger.Silent,
+	})
+	if err != nil {
+		t.Fatalf("NewStore failed: %v", err)
+	}
+	defer store.Close()
+
+	// Already-cancelled context should cause Optimize to fail
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err = store.Optimize(ctx)
+	if err == nil {
+		t.Error("expected error with cancelled context, got nil")
+	}
+}

internal/db/interface.go

@@ -57,6 +57,7 @@ type PromptReader interface {
 	GetAllPrompts(ctx context.Context) ([]*models.UserPromptWithSession, error)
 	GetRecentUserPromptsByProject(ctx context.Context, project string, limit int) ([]*models.UserPromptWithSession, error)
 	FindRecentPromptByText(ctx context.Context, claudeSessionID, promptText string, withinSeconds int) (int64, int, bool)
+	FindRecentPromptByTextGlobal(ctx context.Context, promptText string, withinSeconds int) (int64, int, bool)
 }
 
 // PromptWriter defines write operations for prompts.

internal/embedding/assets.go

@@ -1,14 +1,12 @@
-// Package embedding provides text embedding generation using all-MiniLM-L6-v2.
+// Package embedding provides text embedding generation using bge-small-en-v1.5.
 package embedding
 
 import (
 	_ "embed"
 )
 
-// Model and tokenizer files - embedded for all platforms
+// Tokenizer file - embedded for all platforms (small, not in LFS).
+// The ONNX model is downloaded at runtime to ~/.claude-mnemonic/models/.
 //
-//go:embed assets/model.onnx
-var modelData []byte
-
 //go:embed assets/tokenizer.json
 var tokenizerData []byte

internal/embedding/assets/lib/darwin-arm64/.version

@@ -1 +1 @@
-1.23.2
+1.26.0

internal/embedding/assets/lib/linux-amd64/.version

@@ -1 +1 @@
-1.23.2
+1.26.0

internal/embedding/assets/lib/linux-arm64/.version

@@ -1 +1 @@
-1.23.2
+1.26.0

internal/embedding/assets/lib/windows-amd64/.version

@@ -1 +1 @@
-1.23.2
+1.26.0

internal/embedding/model.go

@@ -2,6 +2,7 @@
 package embedding
 
 import (
+	"context"
 	"fmt"
 	"sync"
 )
@@ -44,6 +45,14 @@ type EmbeddingModel interface {
 	// EmbedBatch generates embeddings for multiple texts.
 	EmbedBatch(texts []string) ([][]float32, error)
 
+	// EmbedWithContext generates an embedding for a single text with context-aware cancellation.
+	// The context controls mutex acquisition timeout — if ctx is cancelled while waiting
+	// for the model lock, the call returns immediately with ctx.Err().
+	EmbedWithContext(ctx context.Context, text string) ([]float32, error)
+
+	// EmbedBatchWithContext generates embeddings for multiple texts with context-aware cancellation.
+	EmbedBatchWithContext(ctx context.Context, texts []string) ([][]float32, error)
+
 	// Close releases model resources.
 	Close() error
 }

internal/embedding/service.go

@@ -3,13 +3,16 @@ package embedding
 
 import (
 	"bytes"
+	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 
+	"github.com/lukaszraczylo/claude-mnemonic/internal/models"
 	"github.com/sugarme/tokenizer"
 	"github.com/sugarme/tokenizer/pretrained"
 	ort "github.com/yalue/onnxruntime_go"
@@ -27,6 +30,13 @@ const (
 	BGEModelName = "bge-small-en-v1.5"
 	// DefaultModelVersion is the default model to use
 	DefaultModelVersion = BGEModelVersion
+
+	// BGEAssetName is the local filename for the BGE model.
+	BGEAssetName = "bge-small-en-v1.5-model.onnx"
+	// BGEAssetURL is the Hugging Face URL for the BGE ONNX model.
+	BGEAssetURL = "https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx"
+	// BGEModelSHA256 is the expected SHA-256 of the BGE model file.
+	BGEModelSHA256 = "828e1496d7fabb79cfa4dcd84fa38625c0d3d21da474a00f08db0f559940cf35"
 )
 
 // MaxSequenceLength is the maximum token sequence length for the model.
@@ -58,6 +68,7 @@ var _ EmbeddingModel = (*bgeModel)(nil)
 var _ ONNXConfigurer = (*bgeModel)(nil)
 
 // newBGEModel creates a new BGE embedding model using bundled ONNX runtime and model.
+// The ONNX model is downloaded at runtime from GitHub Releases and cached to disk.
 func newBGEModel() (EmbeddingModel, error) {
 	// Extract ONNX runtime library to temp directory
 	libDir, err := extractONNXLibrary()
@@ -69,8 +80,10 @@ func newBGEModel() (EmbeddingModel, error) {
 	libPath := filepath.Join(libDir, onnxRuntimeLibName)
 	ort.SetSharedLibraryPath(libPath)
 
-	// Initialize ONNX runtime
-	if err := ort.InitializeEnvironment(); err != nil {
+	// Initialize ONNX runtime (idempotent - ignore "already initialized" since
+	// the ONNX environment is process-global and shared with the reranking service)
+	err = ort.InitializeEnvironment()
+	if err != nil && !strings.Contains(err.Error(), "already been initialized") {
 		return nil, fmt.Errorf("initialize ONNX runtime: %w", err)
 	}
 
@@ -80,9 +93,15 @@ func newBGEModel() (EmbeddingModel, error) {
 		return nil, fmt.Errorf("load tokenizer: %w", err)
 	}
 
-	// Create ONNX session using model-specific configuration
+	// Download model on first use (cached to ~/.claude-mnemonic/models/)
+	modelPath, err := models.EnsureModel(BGEAssetName, BGEAssetURL, BGEModelSHA256)
+	if err != nil {
+		return nil, fmt.Errorf("ensure embedding model: %w", err)
+	}
+
+	// Create ONNX session from file path using model-specific configuration
 	config := bgeONNXConfig
-	session, err := ort.NewDynamicAdvancedSessionWithONNXData(modelData, config.InputNames, config.OutputNames, nil)
+	session, err := ort.NewDynamicAdvancedSession(modelPath, config.InputNames, config.OutputNames, nil)
 	if err != nil {
 		return nil, fmt.Errorf("create ONNX session: %w", err)
 	}
@@ -222,6 +241,103 @@ func (m *bgeModel) EmbedBatch(texts []string) ([][]float32, error) {
 	return results, nil
 }
 
+// acquireMutex attempts to acquire the model mutex, respecting context cancellation.
+// On success the caller MUST call the returned unlock function.
+// If ctx is cancelled while waiting, returns ctx.Err() and no unlock is needed.
+func (m *bgeModel) acquireMutex(ctx context.Context) (unlock func(), err error) {
+	acquired := make(chan struct{})
+	go func() {
+		m.mu.Lock()
+		close(acquired)
+	}()
+
+	select {
+	case <-acquired:
+		// Got the lock normally.
+		return m.mu.Unlock, nil
+	case <-ctx.Done():
+		// Context cancelled while waiting. The goroutine above will eventually
+		// acquire the mutex — we must ensure it gets unlocked.
+		go func() {
+			<-acquired
+			m.mu.Unlock()
+		}()
+		return nil, ctx.Err()
+	}
+}
+
+// EmbedWithContext generates an embedding for a single text with context-aware mutex acquisition.
+// If ctx is cancelled while waiting for the model lock, returns immediately with ctx.Err().
+func (m *bgeModel) EmbedWithContext(ctx context.Context, text string) ([]float32, error) {
+	if text == "" {
+		return make([]float32, EmbeddingDim), nil
+	}
+
+	unlock, err := m.acquireMutex(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("acquire embedding lock: %w", err)
+	}
+	defer unlock()
+
+	results, err := m.computeBatch([]string{text})
+	if err != nil {
+		return nil, err
+	}
+	if len(results) == 0 {
+		return make([]float32, EmbeddingDim), nil
+	}
+	return results[0], nil
+}
+
+// EmbedBatchWithContext generates embeddings for multiple texts with context-aware mutex acquisition.
+func (m *bgeModel) EmbedBatchWithContext(ctx context.Context, texts []string) ([][]float32, error) {
+	if len(texts) == 0 {
+		return nil, nil
+	}
+
+	// Filter out empty texts and track indices
+	nonEmpty := make([]string, 0, len(texts))
+	indices := make([]int, 0, len(texts))
+	for i, t := range texts {
+		if t != "" {
+			nonEmpty = append(nonEmpty, t)
+			indices = append(indices, i)
+		}
+	}
+
+	// If all texts are empty, return zero vectors
+	if len(nonEmpty) == 0 {
+		results := make([][]float32, len(texts))
+		for i := range results {
+			results[i] = make([]float32, EmbeddingDim)
+		}
+		return results, nil
+	}
+
+	unlock, err := m.acquireMutex(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("acquire embedding lock: %w", err)
+	}
+	defer unlock()
+
+	// Compute embeddings for non-empty texts
+	embeddings, err := m.computeBatch(nonEmpty)
+	if err != nil {
+		return nil, fmt.Errorf("compute batch embeddings: %w", err)
+	}
+
+	// Build result with zero vectors for empty texts
+	results := make([][]float32, len(texts))
+	for i := range results {
+		results[i] = make([]float32, EmbeddingDim)
+	}
+	for i, idx := range indices {
+		results[idx] = embeddings[i]
+	}
+
+	return results, nil
+}
+
 // computeBatch runs inference on a batch of texts. Must be called with lock held.
 func (m *bgeModel) computeBatch(sentences []string) ([][]float32, error) {
 	if len(sentences) == 0 {
@@ -506,6 +622,17 @@ func (s *Service) EmbedBatch(texts []string) ([][]float32, error) {
 	return s.model.EmbedBatch(texts)
 }
 
+// EmbedWithContext generates an embedding with context-aware cancellation.
+// If ctx is cancelled while waiting for the model lock, returns immediately.
+func (s *Service) EmbedWithContext(ctx context.Context, text string) ([]float32, error) {
+	return s.model.EmbedWithContext(ctx, text)
+}
+
+// EmbedBatchWithContext generates embeddings with context-aware cancellation.
+func (s *Service) EmbedBatchWithContext(ctx context.Context, texts []string) ([][]float32, error) {
+	return s.model.EmbedBatchWithContext(ctx, texts)
+}
+
 // Close releases model resources.
 func (s *Service) Close() error {
 	return s.model.Close()

internal/embedding/service_test.go

@@ -1,9 +1,12 @@
 package embedding
 
 import (
+	"context"
+	"errors"
 	"math"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -310,6 +313,146 @@ func TestEmbed_Deterministic(t *testing.T) {
 	}
 }
 
+// --- Regression tests: context-aware mutex (Fix #45) ---
+
+// asBGE casts the service model to *bgeModel for direct mutex access.
+// Tests are in the same package so this is safe.
+func asBGE(t *testing.T, svc *Service) *bgeModel {
+	t.Helper()
+	m, ok := svc.model.(*bgeModel)
+	require.True(t, ok, "model is not *bgeModel — test invariant broken")
+	return m
+}
+
+// holdMutex locks m.mu in a background goroutine and returns a release func.
+// The returned ready channel is closed once the lock is held.
+func holdMutex(m *bgeModel) (ready <-chan struct{}, release func()) {
+	ch := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		m.mu.Lock()
+		close(ch)   // signal: lock acquired
+		<-done      // wait for release signal
+		m.mu.Unlock()
+	}()
+	return ch, func() { close(done) }
+}
+
+// TestEmbedWithContext_CancelWhileWaitingForMutex is the core regression test.
+// If the mutex is held and the context times out, EmbedWithContext must return
+// immediately with a context error — not block until the mutex is released.
+func TestEmbedWithContext_CancelWhileWaitingForMutex(t *testing.T) {
+	svc, err := NewService()
+	require.NoError(t, err)
+	defer svc.Close()
+
+	m := asBGE(t, svc)
+
+	// Hold the mutex to simulate a stuck ONNX call.
+	ready, release := holdMutex(m)
+	<-ready // ensure lock is held before proceeding
+	defer release()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	_, err = svc.EmbedWithContext(ctx, "test text")
+	elapsed := time.Since(start)
+
+	// Must return a context error.
+	require.Error(t, err)
+	assert.True(t,
+		errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled),
+		"expected context error, got: %v", err)
+
+	// Must return quickly (well under the 30 s default; allow 2× the timeout for CI slack).
+	assert.Less(t, elapsed, 200*time.Millisecond,
+		"EmbedWithContext blocked too long: %v", elapsed)
+}
+
+// TestEmbedWithContext_SuccessWhenUncontended verifies normal operation still works.
+func TestEmbedWithContext_SuccessWhenUncontended(t *testing.T) {
+	svc, err := NewService()
+	require.NoError(t, err)
+	defer svc.Close()
+
+	emb, err := svc.EmbedWithContext(context.Background(), "hello world")
+	require.NoError(t, err)
+
+	assert.Len(t, emb, EmbeddingDim)
+
+	var sum float32
+	for _, v := range emb {
+		sum += v * v
+	}
+	assert.Greater(t, sum, float32(0), "embedding should not be all zeros")
+}
+
+// TestEmbedBatchWithContext_CancelDuringBatch verifies batch embedding respects
+// context cancellation while blocked on mutex acquisition.
+func TestEmbedBatchWithContext_CancelDuringBatch(t *testing.T) {
+	svc, err := NewService()
+	require.NoError(t, err)
+	defer svc.Close()
+
+	m := asBGE(t, svc)
+
+	ready, release := holdMutex(m)
+	<-ready
+	defer release()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	_, err = svc.EmbedBatchWithContext(ctx, []string{"a", "b", "c"})
+	elapsed := time.Since(start)
+
+	require.Error(t, err)
+	assert.True(t,
+		errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled),
+		"expected context error, got: %v", err)
+	assert.Less(t, elapsed, 200*time.Millisecond,
+		"EmbedBatchWithContext blocked too long: %v", elapsed)
+}
+
+// TestEmbedWithContext_CleanupAfterCancel verifies the cleanup goroutine in
+// acquireMutex properly unlocks the mutex after context cancellation,
+// so subsequent calls do not deadlock.
+func TestEmbedWithContext_CleanupAfterCancel(t *testing.T) {
+	svc, err := NewService()
+	require.NoError(t, err)
+	defer svc.Close()
+
+	m := asBGE(t, svc)
+
+	// --- first call: context expires while mutex is held ---
+	ready, release := holdMutex(m)
+	<-ready
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	_, firstErr := svc.EmbedWithContext(ctx, "should fail")
+	require.Error(t, firstErr)
+	assert.True(t,
+		errors.Is(firstErr, context.DeadlineExceeded) || errors.Is(firstErr, context.Canceled),
+		"expected context error on first call, got: %v", firstErr)
+
+	// Release the held mutex so the cleanup goroutine inside acquireMutex can finish.
+	release()
+
+	// Give the cleanup goroutine a moment to acquire-and-release the mutex.
+	// 50 ms is generous; the goroutine only has to lock+unlock with no contention.
+	time.Sleep(50 * time.Millisecond)
+
+	// --- second call: mutex should be free, no deadlock ---
+	emb, secondErr := svc.EmbedWithContext(context.Background(), "should work")
+	require.NoError(t, secondErr, "second call should succeed after cleanup goroutine released mutex")
+	assert.Len(t, emb, EmbeddingDim)
+}
+
 // Helper function to calculate cosine similarity
 func cosineSimilarity(a, b []float32) float64 {
 	if len(a) != len(b) {

internal/graph/graph_test.go

@@ -0,0 +1,674 @@
+//go:build fts5
+
+package graph
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+	"time"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---- helpers ----------------------------------------------------------------
+
+func makeObs(id int64, sessionID string, concepts, filesRead, filesModified []string) *models.Observation {
+	return &models.Observation{
+		ID:             id,
+		SDKSessionID:   sessionID,
+		Title:          sql.NullString{String: "title", Valid: true},
+		Project:        "test-project",
+		Type:           models.ObsTypeDecision,
+		Concepts:       concepts,
+		FilesRead:      filesRead,
+		FilesModified:  filesModified,
+		CreatedAtEpoch: time.Now().UnixMilli(),
+	}
+}
+
+// ---- ObservationGraph -------------------------------------------------------
+
+func TestNewObservationGraph_Empty(t *testing.T) {
+	g := NewObservationGraph()
+	require.NotNil(t, g)
+
+	stats := g.Stats()
+	assert.Equal(t, 0, stats.NodeCount)
+	assert.Equal(t, 0, stats.EdgeCount)
+}
+
+func TestAddNode_StoresAndRetrieves(t *testing.T) {
+	g := NewObservationGraph()
+	node := &Node{
+		ID:     42,
+		Degree: 0,
+		Metadata: NodeMetadata{
+			Project: "proj",
+			Type:    "decision",
+			Title:   "test node",
+		},
+	}
+	g.AddNode(node)
+
+	got, err := g.GetNode(42)
+	require.NoError(t, err)
+	assert.Equal(t, int64(42), got.ID)
+	assert.Equal(t, "test node", got.Metadata.Title)
+}
+
+func TestAddNode_OverwritesExisting(t *testing.T) {
+	g := NewObservationGraph()
+	g.AddNode(&Node{ID: 1, Metadata: NodeMetadata{Title: "old"}})
+	g.AddNode(&Node{ID: 1, Metadata: NodeMetadata{Title: "new"}})
+
+	got, err := g.GetNode(1)
+	require.NoError(t, err)
+	assert.Equal(t, "new", got.Metadata.Title)
+}
+
+func TestGetNode_NotFound(t *testing.T) {
+	g := NewObservationGraph()
+	_, err := g.GetNode(999)
+	assert.Error(t, err)
+}
+
+func TestAddEdge_UpdatesDegree(t *testing.T) {
+	g := NewObservationGraph()
+	g.AddNode(&Node{ID: 1})
+	g.AddNode(&Node{ID: 2})
+
+	g.AddEdge(Edge{FromID: 1, ToID: 2, Relation: RelationTemporal, Weight: 0.8})
+
+	n1, _ := g.GetNode(1)
+	n2, _ := g.GetNode(2)
+	assert.Equal(t, 1, n1.Degree)
+	assert.Equal(t, 1, n2.Degree)
+}
+
+func TestAddEdge_MissingNodesDontPanic(t *testing.T) {
+	g := NewObservationGraph()
+	// Adding edge referencing non-existent nodes must not panic
+	assert.NotPanics(t, func() {
+		g.AddEdge(Edge{FromID: 100, ToID: 200, Relation: RelationConcept, Weight: 0.5})
+	})
+}
+
+// ---- BuildCSR / GetNeighbors ------------------------------------------------
+
+func TestBuildCSR_NoNodes_ReturnsError(t *testing.T) {
+	g := NewObservationGraph()
+	err := g.BuildCSR()
+	assert.Error(t, err)
+}
+
+func TestGetNeighbors_AfterBuildCSR(t *testing.T) {
+	g := NewObservationGraph()
+	for _, id := range []int64{1, 2, 3} {
+		g.AddNode(&Node{ID: id})
+	}
+	g.AddEdge(Edge{FromID: 1, ToID: 2, Relation: RelationTemporal, Weight: 0.8})
+	g.AddEdge(Edge{FromID: 1, ToID: 3, Relation: RelationConcept, Weight: 0.6})
+
+	require.NoError(t, g.BuildCSR())
+
+	neighbors, weights, err := g.GetNeighbors(1)
+	require.NoError(t, err)
+	assert.Len(t, neighbors, 2)
+	assert.Len(t, weights, 2)
+}
+
+func TestGetNeighbors_NodeWithNoOutgoingEdges(t *testing.T) {
+	g := NewObservationGraph()
+	g.AddNode(&Node{ID: 1})
+	g.AddNode(&Node{ID: 2})
+	// Edge only from 2 → 1; node 2 is a leaf from 1's perspective
+	g.AddEdge(Edge{FromID: 2, ToID: 1, Relation: RelationTemporal, Weight: 0.8})
+	require.NoError(t, g.BuildCSR())
+
+	neighbors, weights, err := g.GetNeighbors(1)
+	require.NoError(t, err)
+	assert.Empty(t, neighbors)
+	assert.Empty(t, weights)
+}
+
+func TestGetNeighbors_NodeNotInGraph(t *testing.T) {
+	g := NewObservationGraph()
+	g.AddNode(&Node{ID: 1})
+	require.NoError(t, g.BuildCSR())
+
+	_, _, err := g.GetNeighbors(999)
+	assert.Error(t, err)
+}
+
+// ---- FindHubs ---------------------------------------------------------------
+
+func TestFindHubs_EmptyGraph(t *testing.T) {
+	g := NewObservationGraph()
+	hubs := g.FindHubs(0.1)
+	assert.Nil(t, hubs)
+}
+
+func TestFindHubs_IdentifiesHighDegreeNodes(t *testing.T) {
+	g := NewObservationGraph()
+	// Node 1 connected to everyone else → hub
+	for id := int64(1); id <= 5; id++ {
+		g.AddNode(&Node{ID: id})
+	}
+	for id := int64(2); id <= 5; id++ {
+		g.AddEdge(Edge{FromID: 1, ToID: id, Relation: RelationConcept, Weight: 0.5})
+	}
+
+	hubs := g.FindHubs(0.2) // top 20%
+	assert.Contains(t, hubs, int64(1))
+}
+
+func TestFindHubs_Percentile100_ReturnsEmpty(t *testing.T) {
+	// percentile=1.0 → cutoff = ceil(N * (1 - 1.0)) = ceil(0) = 0 → no hubs
+	g := NewObservationGraph()
+	for id := int64(1); id <= 4; id++ {
+		g.AddNode(&Node{ID: id})
+	}
+	hubs := g.FindHubs(1.0)
+	assert.Empty(t, hubs)
+}
+
+func TestFindHubs_Percentile0_ReturnsAllNodes(t *testing.T) {
+	// percentile=0.0 → cutoff = ceil(N * 1.0) = N → all nodes returned
+	g := NewObservationGraph()
+	for id := int64(1); id <= 4; id++ {
+		g.AddNode(&Node{ID: id})
+	}
+	hubs := g.FindHubs(0.0)
+	assert.Len(t, hubs, 4)
+}
+
+// ---- Stats ------------------------------------------------------------------
+
+func TestStats_EdgeTypesCounted(t *testing.T) {
+	g := NewObservationGraph()
+	for _, id := range []int64{1, 2, 3} {
+		g.AddNode(&Node{ID: id})
+	}
+	g.AddEdge(Edge{FromID: 1, ToID: 2, Relation: RelationTemporal, Weight: 0.8})
+	g.AddEdge(Edge{FromID: 1, ToID: 3, Relation: RelationConcept, Weight: 0.6})
+	g.AddEdge(Edge{FromID: 2, ToID: 3, Relation: RelationConcept, Weight: 0.6})
+
+	stats := g.Stats()
+	assert.Equal(t, 3, stats.NodeCount)
+	assert.Equal(t, 3, stats.EdgeCount)
+	assert.Equal(t, 1, stats.EdgeTypes[RelationTemporal])
+	assert.Equal(t, 2, stats.EdgeTypes[RelationConcept])
+}
+
+func TestStats_DegreeMetrics(t *testing.T) {
+	g := NewObservationGraph()
+	// Node 1: degree 2, nodes 2,3: degree 1 each
+	for _, id := range []int64{1, 2, 3} {
+		g.AddNode(&Node{ID: id})
+	}
+	g.AddEdge(Edge{FromID: 1, ToID: 2, Relation: RelationTemporal, Weight: 0.8})
+	g.AddEdge(Edge{FromID: 1, ToID: 3, Relation: RelationTemporal, Weight: 0.8})
+
+	stats := g.Stats()
+	assert.Equal(t, 2, stats.MaxDegree)
+	assert.Equal(t, 1, stats.MinDegree)
+	assert.InDelta(t, 4.0/3.0, stats.AvgDegree, 0.001)
+}
+
+// ---- BuildFromObservations --------------------------------------------------
+
+func TestBuildFromObservations_SingleObservation_ReturnsError(t *testing.T) {
+	obs := []*models.Observation{makeObs(1, "s1", nil, nil, nil)}
+	// Single observation: DetectEdges returns nil, BuildCSR errors (no nodes never happens
+	// since node was added — but CSR build will succeed with 1 node and 0 edges).
+	g, err := BuildFromObservations(context.Background(), obs)
+	// With 1 node, BuildCSR succeeds (nodes exist); no edges → valid graph.
+	require.NoError(t, err)
+	require.NotNil(t, g)
+	stats := g.Stats()
+	assert.Equal(t, 1, stats.NodeCount)
+	assert.Equal(t, 0, stats.EdgeCount)
+}
+
+func TestBuildFromObservations_SetsNodeMetadata(t *testing.T) {
+	obs := []*models.Observation{
+		{
+			ID:             7,
+			SDKSessionID:   "sess",
+			Project:        "myproject",
+			Type:           models.ObsTypeFeature,
+			Title:          sql.NullString{String: "feature title", Valid: true},
+			IsSuperseded:   true,
+			CreatedAtEpoch: time.Now().UnixMilli(),
+		},
+	}
+	g, err := BuildFromObservations(context.Background(), obs)
+	require.NoError(t, err)
+
+	node, err := g.GetNode(7)
+	require.NoError(t, err)
+	assert.Equal(t, "myproject", node.Metadata.Project)
+	assert.Equal(t, "feature title", node.Metadata.Title)
+	assert.Equal(t, string(models.ObsTypeFeature), node.Metadata.Type)
+	assert.True(t, node.Metadata.IsSuperseded)
+}
+
+func TestBuildFromObservations_TitleMissing_EmptyString(t *testing.T) {
+	obs := []*models.Observation{
+		{
+			ID:             3,
+			SDKSessionID:   "s",
+			Title:          sql.NullString{Valid: false},
+			CreatedAtEpoch: time.Now().UnixMilli(),
+		},
+	}
+	g, err := BuildFromObservations(context.Background(), obs)
+	require.NoError(t, err)
+
+	node, err := g.GetNode(3)
+	require.NoError(t, err)
+	assert.Equal(t, "", node.Metadata.Title)
+}
+
+func TestBuildFromObservations_WithTemporalEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "sess-a", nil, nil, nil),
+		makeObs(2, "sess-a", nil, nil, nil),
+		makeObs(3, "sess-b", nil, nil, nil),
+	}
+	g, err := BuildFromObservations(context.Background(), obs)
+	require.NoError(t, err)
+
+	stats := g.Stats()
+	assert.Equal(t, 3, stats.NodeCount)
+	// obs 1 and 2 share session → 1 temporal edge
+	assert.Equal(t, 1, stats.EdgeTypes[RelationTemporal])
+}
+
+func TestBuildFromObservations_WithConceptEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "s1", []string{"security", "auth"}, nil, nil),
+		makeObs(2, "s2", []string{"security"}, nil, nil),
+		makeObs(3, "s3", []string{"unrelated"}, nil, nil),
+	}
+	g, err := BuildFromObservations(context.Background(), obs)
+	require.NoError(t, err)
+
+	stats := g.Stats()
+	// obs 1 and 2 share "security"
+	assert.GreaterOrEqual(t, stats.EdgeTypes[RelationConcept], 1)
+}
+
+func TestBuildFromObservations_WithFileOverlapEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "s1", nil, []string{"pkg/foo.go", "pkg/bar.go"}, nil),
+		makeObs(2, "s2", nil, []string{"pkg/foo.go", "pkg/baz.go"}, nil),
+	}
+	g, err := BuildFromObservations(context.Background(), obs)
+	require.NoError(t, err)
+
+	stats := g.Stats()
+	// Jaccard({foo,bar},{foo,baz}) = 1/3 ≈ 0.333 > MinFileOverlapForEdge(0.3)
+	assert.GreaterOrEqual(t, stats.EdgeTypes[RelationFileOverlap], 1)
+}
+
+// ---- RelationType.String() --------------------------------------------------
+
+func TestRelationType_String(t *testing.T) {
+	cases := []struct {
+		rt   RelationType
+		want string
+	}{
+		{RelationFileOverlap, "file_overlap"},
+		{RelationSemantic, "semantic"},
+		{RelationTemporal, "temporal"},
+		{RelationConcept, "concept"},
+		{RelationType(99), "unknown"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.want, func(t *testing.T) {
+			assert.Equal(t, tc.want, tc.rt.String())
+		})
+	}
+}
+
+// ---- DetectEdges (edge_detector.go) ----------------------------------------
+
+func TestDetectEdges_LessThanTwo_ReturnsNil(t *testing.T) {
+	edges, err := DetectEdges(context.Background(), nil)
+	assert.NoError(t, err)
+	assert.Nil(t, edges)
+
+	edges, err = DetectEdges(context.Background(), []*models.Observation{makeObs(1, "s", nil, nil, nil)})
+	assert.NoError(t, err)
+	assert.Nil(t, edges)
+}
+
+func TestDetectEdges_SameSession_CreatesTemporalEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "session-x", nil, nil, nil),
+		makeObs(2, "session-x", nil, nil, nil),
+		makeObs(3, "session-x", nil, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	var temporal []Edge
+	for _, e := range edges {
+		if e.Relation == RelationTemporal {
+			temporal = append(temporal, e)
+		}
+	}
+	// Consecutive pairs: (1,2) and (2,3)
+	assert.Len(t, temporal, 2)
+	assert.InDelta(t, 0.8, temporal[0].Weight, 0.001)
+}
+
+func TestDetectEdges_DifferentSessions_NoTemporalEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "sess-a", nil, nil, nil),
+		makeObs(2, "sess-b", nil, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	for _, e := range edges {
+		assert.NotEqual(t, RelationTemporal, e.Relation)
+	}
+}
+
+func TestDetectEdges_EmptySessionID_NoTemporalEdge(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "", nil, nil, nil),
+		makeObs(2, "", nil, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	for _, e := range edges {
+		assert.NotEqual(t, RelationTemporal, e.Relation)
+	}
+}
+
+func TestDetectEdges_SharedConcepts_CreatesConceptEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "s1", []string{"performance", "caching"}, nil, nil),
+		makeObs(2, "s2", []string{"performance"}, nil, nil),
+		makeObs(3, "s3", []string{"caching"}, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	conceptEdges := filterByRelation(edges, RelationConcept)
+	// obs1↔obs2 (performance), obs1↔obs3 (caching) → 2 concept edges
+	assert.Len(t, conceptEdges, 2)
+}
+
+func TestDetectEdges_NoConcepts_NoConceptEdges(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "s1", nil, nil, nil),
+		makeObs(2, "s2", nil, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	assert.Empty(t, filterByRelation(edges, RelationConcept))
+}
+
+func TestDetectEdges_FileOverlap_AboveThreshold_CreatesEdge(t *testing.T) {
+	// Jaccard 2/3 ≈ 0.667 > 0.3 threshold
+	obs := []*models.Observation{
+		makeObs(1, "s1", nil, []string{"a.go", "b.go", "c.go"}, nil),
+		makeObs(2, "s2", nil, []string{"a.go", "b.go", "d.go"}, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	fileEdges := filterByRelation(edges, RelationFileOverlap)
+	require.Len(t, fileEdges, 1)
+	assert.InDelta(t, 2.0/4.0, float64(fileEdges[0].Weight), 0.01)
+}
+
+func TestDetectEdges_FileOverlap_BelowThreshold_NoEdge(t *testing.T) {
+	// Jaccard 1/9 ≈ 0.11 < 0.3 threshold
+	obs := []*models.Observation{
+		makeObs(1, "s1", nil, []string{"a.go", "b.go", "c.go", "d.go", "e.go"}, nil),
+		makeObs(2, "s2", nil, []string{"a.go", "f.go", "g.go", "h.go", "i.go"}, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	assert.Empty(t, filterByRelation(edges, RelationFileOverlap))
+}
+
+func TestDetectEdges_FilesModified_CountsForOverlap(t *testing.T) {
+	obs := []*models.Observation{
+		makeObs(1, "s1", nil, nil, []string{"pkg/core.go", "pkg/util.go"}),
+		makeObs(2, "s2", nil, []string{"pkg/core.go"}, []string{"pkg/util.go"}),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	fileEdges := filterByRelation(edges, RelationFileOverlap)
+	assert.NotEmpty(t, fileEdges)
+}
+
+func TestDetectEdges_NoEdgeDuplicates(t *testing.T) {
+	// Same pair via two concepts → only one concept edge
+	obs := []*models.Observation{
+		makeObs(1, "s1", []string{"security", "auth"}, nil, nil),
+		makeObs(2, "s2", []string{"security", "auth"}, nil, nil),
+	}
+	edges, err := DetectEdges(context.Background(), obs)
+	require.NoError(t, err)
+
+	conceptEdges := filterByRelation(edges, RelationConcept)
+	// Both share security and auth, but deduplication should keep only 1 edge per pair per call
+	// The seen map deduplicates: only first concept that creates the pair wins
+	assert.Len(t, conceptEdges, 1)
+}
+
+// ---- calculateFileOverlap ---------------------------------------------------
+
+func TestCalculateFileOverlap_DisjointSets_Zero(t *testing.T) {
+	result := calculateFileOverlap([]string{"a.go", "b.go"}, []string{"c.go", "d.go"})
+	assert.Equal(t, float32(0.0), result)
+}
+
+func TestCalculateFileOverlap_IdenticalSets_One(t *testing.T) {
+	files := []string{"a.go", "b.go", "c.go"}
+	result := calculateFileOverlap(files, files)
+	assert.InDelta(t, 1.0, float64(result), 0.001)
+}
+
+func TestCalculateFileOverlap_EmptySlices_Zero(t *testing.T) {
+	assert.Equal(t, float32(0.0), calculateFileOverlap(nil, []string{"a.go"}))
+	assert.Equal(t, float32(0.0), calculateFileOverlap([]string{"a.go"}, nil))
+	assert.Equal(t, float32(0.0), calculateFileOverlap(nil, nil))
+}
+
+func TestCalculateFileOverlap_Jaccard_Correct(t *testing.T) {
+	// {a,b,c} ∩ {b,c,d} = {b,c} → 2/4 = 0.5
+	result := calculateFileOverlap([]string{"a", "b", "c"}, []string{"b", "c", "d"})
+	assert.InDelta(t, 0.5, float64(result), 0.001)
+}
+
+func TestCalculateFileOverlap_Duplicates_TreatedAsSet(t *testing.T) {
+	// Duplicates collapse: {a,a,b} → {a,b}; {a,b,b} → {a,b}; Jaccard = 1.0
+	result := calculateFileOverlap([]string{"a", "a", "b"}, []string{"a", "b", "b"})
+	assert.InDelta(t, 1.0, float64(result), 0.001)
+}
+
+// ---- DetectSemanticEdges ----------------------------------------------------
+
+func TestDetectSemanticEdges_AboveThreshold_CreatesEdge(t *testing.T) {
+	// Identical vectors → similarity = 1.0 > 0.85
+	emb := []float32{1.0, 0.0, 0.0}
+	obs := []*models.Observation{makeObs(1, "s", nil, nil, nil), makeObs(2, "s", nil, nil, nil)}
+	embeddings := map[int64][]float32{1: emb, 2: emb}
+
+	edges := DetectSemanticEdges(context.Background(), obs, embeddings)
+	require.Len(t, edges, 1)
+	assert.Equal(t, RelationSemantic, edges[0].Relation)
+	assert.InDelta(t, 1.0, float64(edges[0].Weight), 0.001)
+}
+
+func TestDetectSemanticEdges_BelowThreshold_NoEdge(t *testing.T) {
+	// Orthogonal vectors → similarity = 0.0
+	obs := []*models.Observation{makeObs(1, "s", nil, nil, nil), makeObs(2, "s", nil, nil, nil)}
+	embeddings := map[int64][]float32{
+		1: {1.0, 0.0, 0.0},
+		2: {0.0, 1.0, 0.0},
+	}
+
+	edges := DetectSemanticEdges(context.Background(), obs, embeddings)
+	assert.Empty(t, edges)
+}
+
+func TestDetectSemanticEdges_MissingEmbedding_Skipped(t *testing.T) {
+	obs := []*models.Observation{makeObs(1, "s", nil, nil, nil), makeObs(2, "s", nil, nil, nil)}
+	// Only obs 1 has embedding
+	embeddings := map[int64][]float32{1: {1.0, 0.0, 0.0}}
+
+	edges := DetectSemanticEdges(context.Background(), obs, embeddings)
+	assert.Empty(t, edges)
+}
+
+func TestDetectSemanticEdges_NoDuplicates(t *testing.T) {
+	emb := []float32{0.9, 0.1, 0.0}
+	obs := []*models.Observation{
+		makeObs(1, "s", nil, nil, nil),
+		makeObs(2, "s", nil, nil, nil),
+		makeObs(3, "s", nil, nil, nil),
+	}
+	embeddings := map[int64][]float32{1: emb, 2: emb, 3: emb}
+
+	edges := DetectSemanticEdges(context.Background(), obs, embeddings)
+	// 3 pairs: (1,2),(1,3),(2,3)
+	assert.Len(t, edges, 3)
+}
+
+// ---- cosineSimilarity -------------------------------------------------------
+
+func TestCosineSimilarity_IdenticalVectors(t *testing.T) {
+	v := []float32{1.0, 2.0, 3.0}
+	result := cosineSimilarity(v, v)
+	assert.InDelta(t, 1.0, float64(result), 0.0001)
+}
+
+func TestCosineSimilarity_OppositeVectors(t *testing.T) {
+	a := []float32{1.0, 0.0}
+	b := []float32{-1.0, 0.0}
+	result := cosineSimilarity(a, b)
+	assert.InDelta(t, -1.0, float64(result), 0.0001)
+}
+
+func TestCosineSimilarity_OrthogonalVectors(t *testing.T) {
+	a := []float32{1.0, 0.0}
+	b := []float32{0.0, 1.0}
+	result := cosineSimilarity(a, b)
+	assert.InDelta(t, 0.0, float64(result), 0.0001)
+}
+
+func TestCosineSimilarity_ZeroVector_ReturnsZero(t *testing.T) {
+	a := []float32{0.0, 0.0}
+	b := []float32{1.0, 0.0}
+	assert.Equal(t, float32(0.0), cosineSimilarity(a, b))
+	assert.Equal(t, float32(0.0), cosineSimilarity(b, a))
+}
+
+func TestCosineSimilarity_MismatchedLength_ReturnsZero(t *testing.T) {
+	a := []float32{1.0, 2.0}
+	b := []float32{1.0, 2.0, 3.0}
+	assert.Equal(t, float32(0.0), cosineSimilarity(a, b))
+}
+
+// ---- edgeKey ----------------------------------------------------------------
+
+func TestEdgeKey_Symmetric(t *testing.T) {
+	// Must produce the same key regardless of order
+	assert.Equal(t, edgeKey(1, 2), edgeKey(2, 1))
+	assert.Equal(t, edgeKey(100, 5), edgeKey(5, 100))
+}
+
+func TestEdgeKey_DifferentPairs_DifferentKeys(t *testing.T) {
+	assert.NotEqual(t, edgeKey(1, 2), edgeKey(1, 3))
+	assert.NotEqual(t, edgeKey(1, 2), edgeKey(2, 3))
+}
+
+// ---- pruneEdges -------------------------------------------------------------
+
+func TestPruneEdges_BelowLimit_NoChange(t *testing.T) {
+	edges := []Edge{
+		{FromID: 1, ToID: 2, Weight: 0.9},
+		{FromID: 1, ToID: 3, Weight: 0.7},
+	}
+	pruned := pruneEdges(edges, 5)
+	assert.Len(t, pruned, 2)
+}
+
+func TestPruneEdges_ZeroLimit_ReturnsAll(t *testing.T) {
+	edges := []Edge{{FromID: 1, ToID: 2, Weight: 0.5}}
+	pruned := pruneEdges(edges, 0)
+	assert.Len(t, pruned, 1)
+}
+
+func TestPruneEdges_KeepsHighWeightEdges(t *testing.T) {
+	// Node 1 gets 4 edges, limit is 2 → only the 2 heaviest should survive
+	edges := []Edge{
+		{FromID: 1, ToID: 2, Weight: 0.9},
+		{FromID: 1, ToID: 3, Weight: 0.8},
+		{FromID: 1, ToID: 4, Weight: 0.3},
+		{FromID: 1, ToID: 5, Weight: 0.1},
+	}
+	pruned := pruneEdges(edges, 2)
+
+	weights := make([]float32, len(pruned))
+	for i, e := range pruned {
+		weights[i] = e.Weight
+	}
+	assert.Contains(t, weights, float32(0.9))
+	assert.Contains(t, weights, float32(0.8))
+}
+
+// ---- sortEdgesByWeight ------------------------------------------------------
+
+func TestSortEdgesByWeight_DescendingOrder(t *testing.T) {
+	edges := []Edge{
+		{Weight: 0.3},
+		{Weight: 0.9},
+		{Weight: 0.1},
+		{Weight: 0.7},
+	}
+	sortEdgesByWeight(edges)
+	for i := 1; i < len(edges); i++ {
+		assert.GreaterOrEqual(t, edges[i-1].Weight, edges[i].Weight)
+	}
+}
+
+func TestSortEdgesByWeight_EmptySlice_NoPanic(t *testing.T) {
+	assert.NotPanics(t, func() {
+		sortEdgesByWeight([]Edge{})
+	})
+}
+
+func TestSortEdgesByWeight_SingleElement_Unchanged(t *testing.T) {
+	edges := []Edge{{Weight: 0.5}}
+	sortEdgesByWeight(edges)
+	assert.Equal(t, float32(0.5), edges[0].Weight)
+}
+
+// ---- helpers ----------------------------------------------------------------
+
+func filterByRelation(edges []Edge, rel RelationType) []Edge {
+	var out []Edge
+	for _, e := range edges {
+		if e.Relation == rel {
+			out = append(out, e)
+		}
+	}
+	return out
+}

internal/maintenance/service.go

@@ -151,10 +151,11 @@ func (s *Service) runMaintenance(ctx context.Context) {
 	}
 
 	// Task 3: Optimize database
+	var optimized bool
 	if err := s.store.Optimize(ctx); err != nil {
 		s.log.Error().Err(err).Msg("Failed to optimize database")
 	} else {
-		s.totalOptimizeRun++
+		optimized = true
 	}
 
 	// Task 4: Clean up old prompts (keep last 1000 per session)
@@ -170,6 +171,9 @@ func (s *Service) runMaintenance(ctx context.Context) {
 	s.lastRunTime = time.Now()
 	s.lastRunDuration = time.Since(start)
 	s.totalCleanedObs += totalCleaned
+	if optimized {
+		s.totalOptimizeRun++
+	}
 	s.mu.Unlock()
 
 	s.log.Info().

internal/maintenance/service_test.go

@@ -0,0 +1,727 @@
+//go:build fts5
+
+// Package maintenance provides scheduled maintenance tasks for claude-mnemonic.
+package maintenance
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/rs/zerolog"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/internal/config"
+	gormdb "github.com/lukaszraczylo/claude-mnemonic/internal/db/gorm"
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// testSetup creates a full maintenance service with a real temporary database.
+func testSetup(t *testing.T, cfg *config.Config) (*Service, *gormdb.Store, *gormdb.ObservationStore, *gormdb.PromptStore, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "maintenance_test_*")
+	require.NoError(t, err, "create temp dir")
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	storeCfg := gormdb.Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := gormdb.NewStore(storeCfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	observationStore := gormdb.NewObservationStore(store, nil, nil, nil)
+	summaryStore := gormdb.NewSummaryStore(store)
+	promptStore := gormdb.NewPromptStore(store, nil)
+
+	svc := NewService(store, observationStore, summaryStore, promptStore, nil, cfg, zerolog.Nop())
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return svc, store, observationStore, promptStore, cleanup
+}
+
+// defaultCfg returns a maintenance-enabled config for tests.
+func defaultCfg() *config.Config {
+	cfg := config.Default()
+	cfg.MaintenanceEnabled = true
+	cfg.MaintenanceIntervalHours = 1
+	cfg.ObservationRetentionDays = 0
+	cfg.CleanupStaleObservations = false
+	return cfg
+}
+
+// insertObservation is a helper that inserts an observation and returns its ID.
+func insertObservation(t *testing.T, obsStore *gormdb.ObservationStore, session, project string, seq int) int64 {
+	t.Helper()
+	obs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "test observation",
+	}
+	id, _, err := obsStore.StoreObservation(context.Background(), session, project, obs, seq, 10)
+	require.NoError(t, err)
+	return id
+}
+
+// ---- NewService ----
+
+func TestNewService_ReturnsNonNilService(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	assert.NotNil(t, svc)
+}
+
+func TestNewService_InitializesChannels(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	// stopCh and doneCh must be non-nil so Stop/Wait don't panic.
+	assert.NotNil(t, svc.stopCh)
+	assert.NotNil(t, svc.doneCh)
+}
+
+// ---- Stats ----
+
+func TestStats_DefaultValues(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	stats := svc.Stats()
+
+	assert.Equal(t, true, stats["enabled"])
+	assert.Equal(t, 1, stats["interval_hours"])
+	assert.Equal(t, 0, stats["retention_days"])
+	assert.Equal(t, false, stats["cleanup_stale"])
+	assert.Equal(t, int64(0), stats["total_cleaned_obs"])
+	assert.Equal(t, int64(0), stats["total_optimizes"])
+	assert.Equal(t, false, stats["running"])
+}
+
+func TestStats_ReflectsConfigFields(t *testing.T) {
+	tests := []struct {
+		name        string
+		cfg         *config.Config
+		wantEnabled bool
+		wantHours   int
+		wantDays    int
+		wantStale   bool
+	}{
+		{
+			name: "maintenance disabled",
+			cfg: func() *config.Config {
+				c := defaultCfg()
+				c.MaintenanceEnabled = false
+				return c
+			}(),
+			wantEnabled: false,
+			wantHours:   1,
+			wantDays:    0,
+			wantStale:   false,
+		},
+		{
+			name: "retention and stale cleanup enabled",
+			cfg: func() *config.Config {
+				c := defaultCfg()
+				c.ObservationRetentionDays = 30
+				c.CleanupStaleObservations = true
+				c.MaintenanceIntervalHours = 12
+				return c
+			}(),
+			wantEnabled: true,
+			wantHours:   12,
+			wantDays:    30,
+			wantStale:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			svc, _, _, _, cleanup := testSetup(t, tt.cfg)
+			defer cleanup()
+
+			stats := svc.Stats()
+			assert.Equal(t, tt.wantEnabled, stats["enabled"])
+			assert.Equal(t, tt.wantHours, stats["interval_hours"])
+			assert.Equal(t, tt.wantDays, stats["retention_days"])
+			assert.Equal(t, tt.wantStale, stats["cleanup_stale"])
+		})
+	}
+}
+
+// ---- Stop (idempotency) ----
+
+func TestStop_WhenNotRunning_DoesNotPanic(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	// Service was never started — Stop must be a no-op.
+	assert.NotPanics(t, func() { svc.Stop() })
+}
+
+func TestStop_CalledTwice_DoesNotPanic(t *testing.T) {
+	// Start with maintenance disabled so Start() returns immediately.
+	cfg := defaultCfg()
+	cfg.MaintenanceEnabled = false
+
+	svc, _, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+	go svc.Start(ctx)
+	svc.Wait() // drains doneCh after early return
+
+	// Stop after Wait — must not panic or double-close.
+	assert.NotPanics(t, func() { svc.Stop() })
+}
+
+// ---- Start / running flag ----
+
+func TestStart_MaintenanceDisabled_ExitsImmediately(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.MaintenanceEnabled = false
+
+	svc, _, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+	go svc.Start(ctx)
+
+	done := make(chan struct{})
+	go func() {
+		svc.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Good — returned without blocking.
+	case <-time.After(2 * time.Second):
+		t.Fatal("Start() did not return promptly when maintenance is disabled")
+	}
+
+	stats := svc.Stats()
+	assert.Equal(t, false, stats["running"])
+}
+
+func TestStart_StopSignal_ExitsCleanly(t *testing.T) {
+	// Start() with maintenance disabled exits immediately — verified in
+	// TestStart_MaintenanceDisabled_ExitsImmediately.
+	//
+	// The ticker/stop path is hard to test because Start() always sleeps
+	// 5 minutes before entering the loop. We verify instead that Stop()
+	// on an already-stopped service is safe and that the doneCh is closed
+	// after exit (i.e., Wait() returns).
+	cfg := defaultCfg()
+	cfg.MaintenanceEnabled = false
+
+	svc, _, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	go svc.Start(context.Background())
+
+	done := make(chan struct{})
+	go func() {
+		svc.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// doneCh was closed — Start exited and Wait returned.
+	case <-time.After(2 * time.Second):
+		t.Fatal("Wait() did not return after Start exited")
+	}
+
+	// Stop after Wait must be a no-op and must not panic.
+	assert.NotPanics(t, func() { svc.Stop() })
+}
+
+func TestStart_DoubleStart_SecondCallIsNoOp(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.MaintenanceEnabled = false // exits immediately
+
+	svc, _, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// First call.
+	go svc.Start(ctx)
+	svc.Wait()
+
+	// Second call on the same (exhausted) svc should be a no-op and not panic.
+	assert.NotPanics(t, func() {
+		// svc.running is now false again — but doneCh is already closed.
+		// A second Start would attempt to close doneCh again which would panic
+		// if the running guard is missing. Verify the guard works.
+		svc.mu.Lock()
+		running := svc.running
+		svc.mu.Unlock()
+		assert.False(t, running)
+	})
+}
+
+// ---- RunNow ----
+
+func TestRunNow_UpdatesLastRunTime(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.ObservationRetentionDays = 0
+	cfg.CleanupStaleObservations = false
+
+	svc, _, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	before := time.Now()
+	svc.RunNow(context.Background())
+
+	// Allow async goroutine to finish.
+	time.Sleep(200 * time.Millisecond)
+
+	svc.mu.Lock()
+	lastRun := svc.lastRunTime
+	svc.mu.Unlock()
+
+	assert.True(t, lastRun.After(before) || lastRun.Equal(before),
+		"lastRunTime should be updated after RunNow")
+}
+
+func TestRunNow_IncrementsOptimizeCounter(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	svc.RunNow(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	svc.mu.Lock()
+	optimizes := svc.totalOptimizeRun
+	svc.mu.Unlock()
+
+	assert.Equal(t, int64(1), optimizes)
+}
+
+func TestRunNow_StatsTotalOptimizesReflected(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	svc.RunNow(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	stats := svc.Stats()
+	assert.Equal(t, int64(1), stats["total_optimizes"])
+}
+
+// ---- cleanupOldObservations (via RunNow) ----
+
+func TestRunNow_RetentionDaysZero_NothingDeleted(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.ObservationRetentionDays = 0
+
+	svc, _, obsStore, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	// Insert observations.
+	for i := 0; i < 5; i++ {
+		insertObservation(t, obsStore, "session-1", "proj", i)
+	}
+
+	svc.RunNow(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	remaining, err := obsStore.GetRecentObservations(context.Background(), "proj", 20)
+	require.NoError(t, err)
+	assert.Equal(t, 5, len(remaining), "nothing should be deleted when retention_days = 0")
+
+	svc.mu.Lock()
+	cleaned := svc.totalCleanedObs
+	svc.mu.Unlock()
+	assert.Equal(t, int64(0), cleaned)
+}
+
+func TestRunNow_RetentionDays_DeletesExpiredObservations(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.ObservationRetentionDays = 1 // keep only last 1 day
+
+	svc, store, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Insert an observation and back-date it to 2 days ago.
+	obs := &gormdb.Observation{
+		SDKSessionID:   "old-session",
+		Project:        "proj",
+		Type:           models.ObsTypeDiscovery,
+		CreatedAt:      "2000-01-01T00:00:00Z",
+		CreatedAtEpoch: time.Now().AddDate(0, 0, -2).Unix(),
+		Scope:          models.ScopeProject,
+		ImportanceScore: 1.0,
+	}
+	require.NoError(t, store.GetDB().WithContext(ctx).Create(obs).Error)
+
+	// Insert a recent observation (should survive).
+	recentObs := &gormdb.Observation{
+		SDKSessionID:   "new-session",
+		Project:        "proj",
+		Type:           models.ObsTypeDiscovery,
+		CreatedAt:      time.Now().Format(time.RFC3339),
+		CreatedAtEpoch: time.Now().Unix(),
+		Scope:          models.ScopeProject,
+		ImportanceScore: 1.0,
+	}
+	require.NoError(t, store.GetDB().WithContext(ctx).Create(recentObs).Error)
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	// Only the recent observation should remain.
+	var count int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Count(&count)
+	assert.Equal(t, int64(1), count, "expired observation should have been deleted")
+
+	svc.mu.Lock()
+	cleaned := svc.totalCleanedObs
+	svc.mu.Unlock()
+	assert.Equal(t, int64(1), cleaned)
+}
+
+func TestRunNow_RetentionDays_VectorCleanupCalled(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.ObservationRetentionDays = 1
+
+	tmpDir, err := os.MkdirTemp("", "maintenance_vec_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	store, err := gormdb.NewStore(gormdb.Config{
+		Path:     filepath.Join(tmpDir, "test.db"),
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	})
+	require.NoError(t, err)
+	defer store.Close()
+
+	observationStore := gormdb.NewObservationStore(store, nil, nil, nil)
+	summaryStore := gormdb.NewSummaryStore(store)
+	promptStore := gormdb.NewPromptStore(store, nil)
+
+	var mu sync.Mutex
+	var capturedIDs []int64
+
+	vectorCleanupFn := func(_ context.Context, ids []int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		capturedIDs = append(capturedIDs, ids...)
+	}
+
+	svc := NewService(store, observationStore, summaryStore, promptStore, vectorCleanupFn, cfg, zerolog.Nop())
+
+	ctx := context.Background()
+
+	// Insert an expired observation directly.
+	obs := &gormdb.Observation{
+		SDKSessionID:   "session-x",
+		Project:        "proj",
+		Type:           models.ObsTypeDiscovery,
+		CreatedAt:      "2000-01-01T00:00:00Z",
+		CreatedAtEpoch: time.Now().AddDate(0, 0, -2).Unix(),
+		Scope:          models.ScopeProject,
+		ImportanceScore: 1.0,
+	}
+	require.NoError(t, store.GetDB().WithContext(ctx).Create(obs).Error)
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	mu.Lock()
+	ids := capturedIDs
+	mu.Unlock()
+
+	assert.NotEmpty(t, ids, "vector cleanup callback must be called with deleted IDs")
+	assert.Contains(t, ids, obs.ID)
+}
+
+// ---- cleanupStaleObservations (via RunNow) ----
+
+func TestRunNow_CleanupStale_DeletesSupersededObservations(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.CleanupStaleObservations = true
+	cfg.ObservationRetentionDays = 0
+
+	svc, store, obsStore, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Insert an active observation.
+	activeID := insertObservation(t, obsStore, "session-1", "proj", 1)
+
+	// Insert and mark a stale observation.
+	staleID := insertObservation(t, obsStore, "session-1", "proj", 2)
+	require.NoError(t, store.GetDB().WithContext(ctx).
+		Model(&gormdb.Observation{}).
+		Where("id = ?", staleID).
+		Update("is_superseded", 1).Error)
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	// Active observation must survive.
+	var activeCount int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Where("id = ?", activeID).Count(&activeCount)
+	assert.Equal(t, int64(1), activeCount, "active observation must not be deleted")
+
+	// Stale observation must be gone.
+	var staleCount int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Where("id = ?", staleID).Count(&staleCount)
+	assert.Equal(t, int64(0), staleCount, "stale observation must be deleted")
+}
+
+func TestRunNow_CleanupStale_DisabledLeavesStaleObservations(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.CleanupStaleObservations = false
+
+	svc, store, obsStore, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	staleID := insertObservation(t, obsStore, "session-1", "proj", 1)
+	require.NoError(t, store.GetDB().WithContext(ctx).
+		Model(&gormdb.Observation{}).
+		Where("id = ?", staleID).
+		Update("is_superseded", 1).Error)
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	var count int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Where("id = ?", staleID).Count(&count)
+	assert.Equal(t, int64(1), count, "stale observation must survive when cleanup_stale is false")
+}
+
+func TestRunNow_CleanupStale_NoStaleRows_NothingChanged(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.CleanupStaleObservations = true
+
+	svc, _, obsStore, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Only active observations.
+	for i := 0; i < 3; i++ {
+		insertObservation(t, obsStore, "session-1", "proj", i)
+	}
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	remaining, err := obsStore.GetRecentObservations(ctx, "proj", 20)
+	require.NoError(t, err)
+	assert.Equal(t, 3, len(remaining))
+}
+
+// ---- cleanupOldPrompts (via RunNow) ----
+
+func TestRunNow_CleanupOldPrompts_DeletesExpiredPrompts(t *testing.T) {
+	svc, store, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Insert a prompt with an old epoch (31 days ago).
+	oldPrompt := &gormdb.UserPrompt{
+		ClaudeSessionID: "session-old",
+		PromptText:      "old prompt",
+		PromptNumber:    1,
+		CreatedAt:       "2000-01-01T00:00:00Z",
+		CreatedAtEpoch:  time.Now().AddDate(0, 0, -31).Unix(),
+	}
+	require.NoError(t, store.GetDB().WithContext(ctx).Create(oldPrompt).Error)
+
+	// Insert a recent prompt (should survive).
+	recentPrompt := &gormdb.UserPrompt{
+		ClaudeSessionID: "session-new",
+		PromptText:      "recent prompt",
+		PromptNumber:    1,
+		CreatedAt:       time.Now().Format(time.RFC3339),
+		CreatedAtEpoch:  time.Now().Unix(),
+	}
+	require.NoError(t, store.GetDB().WithContext(ctx).Create(recentPrompt).Error)
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	var count int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.UserPrompt{}).Count(&count)
+	assert.Equal(t, int64(1), count, "only the recent prompt should survive")
+}
+
+func TestRunNow_CleanupOldPrompts_NothingExpired_AllSurvive(t *testing.T) {
+	svc, store, _, promptStore, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	ctx := context.Background()
+
+	for i := 1; i <= 5; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "session-1", i, "prompt", 1)
+		require.NoError(t, err)
+	}
+
+	svc.RunNow(ctx)
+	time.Sleep(300 * time.Millisecond)
+
+	var count int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.UserPrompt{}).Count(&count)
+	assert.Equal(t, int64(5), count, "no prompts should be deleted when none are expired")
+}
+
+// ---- Stats race safety ----
+
+func TestStats_ConcurrentAccess_NoRace(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_ = svc.Stats()
+		}()
+	}
+	wg.Wait()
+}
+
+// ---- RunNow concurrent safety ----
+
+func TestRunNow_ConcurrentCalls_NoRace(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	ctx := context.Background()
+	var wg sync.WaitGroup
+	for i := 0; i < 5; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			svc.RunNow(ctx)
+		}()
+	}
+	wg.Wait()
+	time.Sleep(500 * time.Millisecond)
+}
+
+// ---- lastRunDuration is populated ----
+
+func TestRunNow_LastRunDuration_IsPopulated(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	svc.RunNow(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	svc.mu.Lock()
+	dur := svc.lastRunDuration
+	svc.mu.Unlock()
+
+	assert.Greater(t, int64(dur), int64(0), "lastRunDuration should be set after a maintenance run")
+}
+
+func TestStats_LastDurationMs_IsPopulated(t *testing.T) {
+	svc, _, _, _, cleanup := testSetup(t, defaultCfg())
+	defer cleanup()
+
+	svc.RunNow(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	stats := svc.Stats()
+	// The value is int64 milliseconds; it might be 0 for very fast runs — just verify the key exists.
+	_, ok := stats["last_duration_ms"]
+	assert.True(t, ok, "stats must contain last_duration_ms key")
+}
+
+// ---- Batch deletion boundary ----
+
+func TestRunNow_RetentionDays_BatchDeletion_MoreThan100Rows(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.ObservationRetentionDays = 1
+
+	svc, store, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Insert 150 expired observations (forces 2 batches of 100).
+	for i := 0; i < 150; i++ {
+		obs := &gormdb.Observation{
+			SDKSessionID:   "session-old",
+			Project:        "proj",
+			Type:           models.ObsTypeDiscovery,
+			CreatedAt:      "2000-01-01T00:00:00Z",
+			CreatedAtEpoch: time.Now().AddDate(0, 0, -2).Unix(),
+			Scope:          models.ScopeProject,
+			ImportanceScore: 1.0,
+		}
+		require.NoError(t, store.GetDB().WithContext(ctx).Create(obs).Error)
+	}
+
+	svc.RunNow(ctx)
+	time.Sleep(500 * time.Millisecond)
+
+	var remaining int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Count(&remaining)
+	assert.Equal(t, int64(0), remaining, "all 150 expired observations should be deleted in batches")
+
+	svc.mu.Lock()
+	cleaned := svc.totalCleanedObs
+	svc.mu.Unlock()
+	assert.Equal(t, int64(150), cleaned)
+}
+
+func TestRunNow_CleanupStale_BatchDeletion_MoreThan100Rows(t *testing.T) {
+	cfg := defaultCfg()
+	cfg.CleanupStaleObservations = true
+
+	svc, store, _, _, cleanup := testSetup(t, cfg)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Insert 120 superseded observations.
+	for i := 0; i < 120; i++ {
+		obs := &gormdb.Observation{
+			SDKSessionID:   "session-stale",
+			Project:        "proj",
+			Type:           models.ObsTypeDiscovery,
+			CreatedAt:      time.Now().Format(time.RFC3339),
+			CreatedAtEpoch: time.Now().Unix(),
+			Scope:          models.ScopeProject,
+			ImportanceScore: 1.0,
+			IsSuperseded:   1,
+		}
+		require.NoError(t, store.GetDB().WithContext(ctx).Create(obs).Error)
+	}
+
+	svc.RunNow(ctx)
+	time.Sleep(500 * time.Millisecond)
+
+	var remaining int64
+	store.GetDB().WithContext(ctx).Model(&gormdb.Observation{}).Where("is_superseded = ?", 1).Count(&remaining)
+	assert.Equal(t, int64(0), remaining, "all 120 stale observations should be deleted in batches")
+}

internal/models/download.go

@@ -0,0 +1,259 @@
+// Package models provides runtime model download and caching.
+// Models are downloaded from Hugging Face on first use and cached
+// to the OS cache directory (~/Library/Caches/claude-mnemonic/models/ on macOS,
+// ~/.cache/claude-mnemonic/models/ on Linux, %LocalAppData%/claude-mnemonic/models/ on Windows).
+// This replaces the previous approach of embedding models in the binary
+// via go:embed and tracking them with Git LFS.
+package models
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/rs/zerolog/log"
+)
+
+const (
+	// ModelVersion is incremented to force re-download of all cached models.
+	ModelVersion = "1"
+
+	maxRetries      = 3
+	retryBaseDelay  = 2 * time.Second
+	progressEvery   = 3 * time.Second
+	downloadTimeout = 15 * time.Minute
+)
+
+// ModelsDir returns the path to the model cache directory.
+// Uses the OS cache dir for cross-platform compatibility:
+//
+//	macOS:   ~/Library/Caches/claude-mnemonic/models
+//	Linux:   ~/.cache/claude-mnemonic/models
+//	Windows: %LocalAppData%/claude-mnemonic/models
+func ModelsDir() string {
+	dir, err := os.UserCacheDir()
+	if err != nil {
+		home, _ := os.UserHomeDir()
+		dir = filepath.Join(home, ".cache")
+	}
+	return filepath.Join(dir, "claude-mnemonic", "models")
+}
+
+// EnsureModel ensures the model file exists and returns its path.
+//
+// Resolution order:
+//  1. CLAUDE_MNEMONIC_MODEL_DIR env var — if set, load models from this directory directly.
+//     This is intended for development and CI where models are already on disk.
+//  2. User cache directory — if the model is already cached and its checksum matches,
+//     return it immediately.
+//  3. url — download the model from the given URL with retries and cache it.
+//
+// assetName is the local filename (e.g. "bge-small-en-v1.5-model.onnx").
+// expectedSHA256 is the hex-encoded SHA-256 of the file.
+func EnsureModel(assetName, url, expectedSHA256 string) (string, error) {
+	if localDir := os.Getenv("CLAUDE_MNEMONIC_MODEL_DIR"); localDir != "" {
+		localPath := filepath.Join(localDir, assetName)
+		if _, err := os.Stat(localPath); err == nil {
+			if valid, err := verifyChecksum(localPath, expectedSHA256); err != nil || !valid {
+				return "", fmt.Errorf("local model %s checksum mismatch", assetName)
+			}
+			return localPath, nil
+		}
+		return "", fmt.Errorf("local model %s not found in %s", assetName, localDir)
+	}
+
+	dir := ModelsDir()
+	versionFile := filepath.Join(dir, ".model_version")
+	modelPath := filepath.Join(dir, assetName)
+
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return "", fmt.Errorf("create model cache dir: %w", err)
+	}
+
+	currentVersion, _ := os.ReadFile(versionFile)
+
+	if string(currentVersion) == ModelVersion {
+		if fi, err := os.Stat(modelPath); err == nil && fi.Size() > 0 {
+			if valid, _ := verifyChecksum(modelPath, expectedSHA256); valid {
+				return modelPath, nil
+			}
+			log.Warn().Str("model", assetName).Msg("Cached model corrupted, re-downloading")
+			os.Remove(modelPath)
+		}
+	} else if len(currentVersion) > 0 {
+		log.Info().Str("old", string(currentVersion)).Str("new", ModelVersion).Msg("Model version updated, clearing cache")
+		os.RemoveAll(dir)
+		if err := os.MkdirAll(dir, 0700); err != nil {
+			return "", fmt.Errorf("create model cache dir: %w", err)
+		}
+	}
+
+	if err := downloadWithRetries(url, modelPath); err != nil {
+		os.Remove(modelPath)
+		return "", fmt.Errorf("download %s: %w", assetName, err)
+	}
+
+	if valid, err := verifyChecksum(modelPath, expectedSHA256); err != nil || !valid {
+		os.Remove(modelPath)
+		return "", fmt.Errorf("downloaded model %s failed checksum verification — the file at %s may have changed", assetName, url)
+	}
+
+	if err := os.WriteFile(versionFile, []byte(ModelVersion), 0600); err != nil {
+		log.Warn().Err(err).Msg("Failed to write model version file")
+	}
+
+	log.Info().Str("model", assetName).Str("cache", dir).Msg("Model ready")
+	return modelPath, nil
+}
+
+func downloadWithRetries(url, dest string) error {
+	var lastErr error
+	for attempt := 0; attempt < maxRetries; attempt++ {
+		if attempt > 0 {
+			delay := retryBaseDelay * time.Duration(1<<(attempt-1))
+			log.Warn().Int("attempt", attempt+1).Int("max", maxRetries).Dur("delay", delay).Msg("Retrying download")
+			time.Sleep(delay)
+		}
+		if err := downloadFile(url, dest); err != nil {
+			lastErr = err
+			continue
+		}
+		return nil
+	}
+	return fmt.Errorf("failed after %d attempts: %w", maxRetries, lastErr)
+}
+
+func downloadFile(url, dest string) error {
+	client := &http.Client{Timeout: downloadTimeout}
+
+	resp, err := client.Get(url)
+	if err != nil {
+		return fmt.Errorf("HTTP GET: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 400 {
+		return fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	tmp := dest + ".tmp"
+	f, err := os.Create(tmp)
+	if err != nil {
+		return fmt.Errorf("create temp file: %w", err)
+	}
+	cleanup := func() { f.Close(); os.Remove(tmp) }
+
+	name := filepath.Base(dest)
+	reader := &progressReader{
+		reader: resp.Body,
+		total:  resp.ContentLength,
+		name:   name,
+	}
+
+	if _, err := io.Copy(f, reader); err != nil {
+		cleanup()
+		return fmt.Errorf("write file: %w", err)
+	}
+
+	if err := f.Sync(); err != nil {
+		cleanup()
+		return fmt.Errorf("sync file: %w", err)
+	}
+	f.Close()
+
+	if err := os.Rename(tmp, dest); err != nil {
+		os.Remove(tmp)
+		return fmt.Errorf("commit file: %w", err)
+	}
+
+	return nil
+}
+
+// progressReader wraps an io.Reader and logs progress for large downloads.
+type progressReader struct {
+	reader    io.Reader
+	total     int64
+	current   int64
+	name      string
+	lastLog   time.Time
+	loggedPct int
+}
+
+func (pr *progressReader) Read(p []byte) (n int, err error) {
+	n, err = pr.reader.Read(p)
+	pr.current += int64(n)
+
+	if time.Since(pr.lastLog) >= progressEvery || err == io.EOF {
+		if pr.total > 0 {
+			pct := int(math.Round(float64(pr.current) / float64(pr.total) * 100))
+			if pct != pr.loggedPct {
+				pr.loggedPct = pct
+				mibCurrent := float64(pr.current) / (1024 * 1024)
+				mibTotal := float64(pr.total) / (1024 * 1024)
+				log.Info().
+					Str("model", pr.name).
+					Int("pct", pct).
+					Str("progress", fmt.Sprintf("%.0f/%.0f MiB", mibCurrent, mibTotal)).
+					Msg("Downloading")
+			}
+		} else {
+			mibCurrent := float64(pr.current) / (1024 * 1024)
+			log.Info().
+				Str("model", pr.name).
+				Str("progress", fmt.Sprintf("%.0f MiB", mibCurrent)).
+				Msg("Downloading (size unknown)")
+		}
+		pr.lastLog = time.Now()
+	}
+
+	return n, err
+}
+
+func verifyChecksum(path, expectedHex string) (bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return false, err
+	}
+	defer f.Close()
+
+	h := sha256.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return false, err
+	}
+
+	actual := hex.EncodeToString(h.Sum(nil))
+	return actual == expectedHex, nil
+}
+
+// CleanStale removes any temporary download files that may have been left behind
+// by a previous interrupted download.
+func CleanStale() error {
+	dir := ModelsDir()
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil
+		}
+		return err
+	}
+
+	for _, e := range entries {
+		if filepath.Ext(e.Name()) == ".tmp" {
+			tmpPath := filepath.Join(dir, e.Name())
+			if info, err := e.Info(); err == nil {
+				if time.Since(info.ModTime()) > time.Hour {
+					os.Remove(tmpPath)
+					log.Debug().Str("file", tmpPath).Msg("Cleaned stale temp file")
+				}
+			}
+		}
+	}
+	return nil
+}

internal/reranking/assets.go

@@ -5,10 +5,8 @@ import (
 	_ "embed"
 )
 
-// Cross-encoder model and tokenizer files - embedded for all platforms
+// Tokenizer file - embedded for all platforms (small, not in LFS).
+// The ONNX model is downloaded at runtime to ~/.claude-mnemonic/models/.
 //
-//go:embed assets/model.onnx
-var crossEncoderModelData []byte
-
 //go:embed assets/tokenizer.json
 var crossEncoderTokenizerData []byte

internal/reranking/service.go

@@ -9,6 +9,7 @@ import (
 	"sort"
 	"sync"
 
+	"github.com/lukaszraczylo/claude-mnemonic/internal/models"
 	"github.com/rs/zerolog/log"
 	"github.com/sugarme/tokenizer"
 	"github.com/sugarme/tokenizer/pretrained"
@@ -26,6 +27,13 @@ const (
 	DefaultCandidateLimit = 100
 	// DefaultResultLimit is the default number of results to return after reranking
 	DefaultResultLimit = 10
+
+	// CrossEncoderAssetName is the local filename for the cross-encoder model.
+	CrossEncoderAssetName = "ms-marco-MiniLM-L6-v2-model.onnx"
+	// CrossEncoderAssetURL is the Hugging Face URL for the cross-encoder ONNX model.
+	CrossEncoderAssetURL = "https://huggingface.co/cross-encoder/ms-marco-MiniLM-L6-v2/resolve/main/onnx/model.onnx"
+	// CrossEncoderModelSHA256 is the expected SHA-256 of the cross-encoder model file.
+	CrossEncoderModelSHA256 = "5d3e70fd0c9ff14b9b5169a51e957b7a9c74897afd0a35ce4bd318150c1d4d4a"
 )
 
 // Candidate represents a search result candidate for reranking.
@@ -91,12 +99,18 @@ func NewService(cfg Config) (*Service, error) {
 		Stride:    0,
 	})
 
+	// Download model on first use (cached to ~/.claude-mnemonic/models/)
+	modelPath, err := models.EnsureModel(CrossEncoderAssetName, CrossEncoderAssetURL, CrossEncoderModelSHA256)
+	if err != nil {
+		return nil, fmt.Errorf("ensure cross-encoder model: %w", err)
+	}
+
 	// Cross-encoder outputs a single logit for relevance scoring
 	inputNames := []string{"input_ids", "attention_mask", "token_type_ids"}
 	outputNames := []string{"logits"}
 
-	session, err := ort.NewDynamicAdvancedSessionWithONNXData(
-		crossEncoderModelData,
+	session, err := ort.NewDynamicAdvancedSession(
+		modelPath,
 		inputNames,
 		outputNames,
 		nil,

internal/search/manager.go

@@ -46,7 +46,7 @@ const (
 	cacheWarmingInterval     = 20 * time.Second // Run warming cycle every 20 seconds
 	frequencyCleanupInterval = 5 * time.Minute  // Cleanup stale entries every 5 minutes
 	cacheCleanupInterval     = time.Minute      // Cleanup expired cache every minute
-	warmingQueryTimeout      = 5 * time.Second  // Timeout for warming queries
+	warmingQueryTimeout      = 2 * time.Second  // Timeout for warming queries (kept short to minimize mutex hold)
 	warmingBatchSize         = 5                // Warm top 5 queries per cycle
 	minRecencyFactor         = 0.1              // Minimum recency factor for scoring
 
@@ -127,6 +127,7 @@ type Manager struct {
 	queryFrequency   map[string]*queryFrequencyInfo
 	cacheTTL         time.Duration
 	cacheMaxSize     int
+	activeQueries    atomic.Int32 // tracks in-flight user queries to yield embedding mutex
 	resultCacheMu    sync.RWMutex
 	queryFrequencyMu sync.RWMutex
 }
@@ -256,7 +257,14 @@ func (m *Manager) cleanupStaleFrequencyEntries() {
 }
 
 // warmFrequentQueries pre-executes frequently used queries to warm the cache.
+// Skips warming entirely when user queries are in-flight to avoid competing
+// for the embedding model mutex on throttled hardware.
 func (m *Manager) warmFrequentQueries() {
+	if m.activeQueries.Load() > 0 {
+		log.Debug().Msg("Skipping cache warming: user queries in flight")
+		return
+	}
+
 	m.queryFrequencyMu.RLock()
 	// Find top N most frequent queries that aren't recently cached
 	type queryScore struct {
@@ -687,30 +695,40 @@ func (m *Manager) UnifiedSearch(ctx context.Context, params SearchParams) (*Unif
 		params.OrderBy = defaultOrderBy
 	}
 
+	// Track active user queries so cache warming can yield the embedding mutex
+	m.activeQueries.Add(1)
+	defer m.activeQueries.Add(-1)
+
 	// Check cache first
 	cacheKey := m.getCacheKey(params)
 	if cached, ok := m.getFromCache(cacheKey); ok {
 		return cached, nil
 	}
 
-	// Use singleflight to coalesce concurrent identical requests
-	result, err, _ := m.searchGroup.Do(cacheKey, func() (any, error) {
+	// Use singleflight DoChan to coalesce concurrent identical requests.
+	// DoChan + select allows per-caller context cancellation: waiting callers
+	// can bail out when their context expires without blocking on a slow first call.
+	ch := m.searchGroup.DoChan(cacheKey, func() (any, error) {
 		return m.executeSearch(ctx, params)
 	})
 
-	if err != nil {
-		return nil, err
+	select {
+	case res := <-ch:
+		if res.Err != nil {
+			return nil, res.Err
+		}
+		searchResult := res.Val.(*UnifiedSearchResult)
+
+		// Cache the result
+		m.putInCache(cacheKey, searchResult)
+
+		// Track query frequency for cache warming
+		m.trackQueryFrequency(params)
+
+		return searchResult, nil
+	case <-ctx.Done():
+		return nil, ctx.Err()
 	}
-
-	searchResult := result.(*UnifiedSearchResult)
-
-	// Cache the result
-	m.putInCache(cacheKey, searchResult)
-
-	// Track query frequency for cache warming
-	m.trackQueryFrequency(params)
-
-	return searchResult, nil
 }
 
 // executeSearch performs the actual search without caching/coalescing.

internal/search/manager_test.go

@@ -1009,6 +1009,91 @@ func TestSearchParams_FormatValues(t *testing.T) {
 	}
 }
 
+// =============================================================================
+// REGRESSION TESTS FOR Fix #3: Cache warming skipped during active queries
+// =============================================================================
+
+// TestCacheWarming_SkippedDuringActiveQueries verifies that warmFrequentQueries
+// returns immediately without doing work when activeQueries > 0, and actually
+// warms when activeQueries == 0.
+func TestCacheWarming_SkippedDuringActiveQueries(t *testing.T) {
+	m := NewManager(nil, nil, nil, nil)
+	defer m.Close()
+
+	// Seed a frequent query so warming has something to consider
+	params := SearchParams{
+		Query:   "test warming query",
+		Project: "test-project",
+		Limit:   10,
+	}
+	m.trackQueryFrequency(params)
+	// Track it multiple times to boost its score
+	for range 5 {
+		m.trackQueryFrequency(params)
+	}
+
+	// Case 1: activeQueries > 0 — warming should be skipped (fast return)
+	m.activeQueries.Store(1)
+
+	start := time.Now()
+	m.warmFrequentQueries()
+	elapsed := time.Since(start)
+
+	// Warming should return almost immediately when skipped
+	assert.Less(t, elapsed, 50*time.Millisecond,
+		"warmFrequentQueries should return quickly when user queries are in flight")
+
+	// Case 2: activeQueries == 0 — warming should proceed past the guard.
+	// With nil stores, executeSearch would panic, so we verify the guard was
+	// bypassed by checking that the frequency map's lastCached is NOT updated
+	// (warming fails silently on nil stores). The key assertion is that Case 1
+	// returns immediately (the guard works) while Case 2 enters the body.
+	m.activeQueries.Store(0)
+
+	// Clear frequency data to prevent executeSearch from being called
+	m.queryFrequencyMu.Lock()
+	m.queryFrequency = make(map[string]*queryFrequencyInfo)
+	m.queryFrequencyMu.Unlock()
+
+	start2 := time.Now()
+	m.warmFrequentQueries()
+	elapsed2 := time.Since(start2)
+
+	// With empty frequency map, warming enters the function body (past guard)
+	// but finds no candidates — fast return without calling executeSearch.
+	assert.Less(t, elapsed2, 200*time.Millisecond,
+		"warmFrequentQueries should complete quickly with no candidates")
+}
+
+// TestActiveQueries_IncrementDecrement verifies that the activeQueries counter
+// is correctly incremented and decremented around search operations.
+func TestActiveQueries_IncrementDecrement(t *testing.T) {
+	m := NewManager(nil, nil, nil, nil)
+	defer m.Close()
+
+	// Before any search, counter should be 0
+	assert.Equal(t, int32(0), m.activeQueries.Load())
+
+	// Directly test the atomic increment/decrement pattern used in UnifiedSearch
+	// (can't call UnifiedSearch with nil stores without panicking on filterSearch)
+	m.activeQueries.Add(1)
+	assert.Equal(t, int32(1), m.activeQueries.Load(), "should be 1 after increment")
+
+	m.activeQueries.Add(1)
+	assert.Equal(t, int32(2), m.activeQueries.Load(), "should be 2 after second increment")
+
+	m.activeQueries.Add(-1)
+	assert.Equal(t, int32(1), m.activeQueries.Load(), "should be 1 after decrement")
+
+	m.activeQueries.Add(-1)
+	assert.Equal(t, int32(0), m.activeQueries.Load(), "should be 0 after final decrement")
+
+	// Verify the field is accessible from warmFrequentQueries guard
+	m.activeQueries.Store(3)
+	assert.Equal(t, int32(3), m.activeQueries.Load())
+	m.activeQueries.Store(0)
+}
+
 // TestUnifiedSearchResult_MultipleResults tests result with multiple items.
 func TestUnifiedSearchResult_MultipleResults(t *testing.T) {
 	results := []SearchResult{

internal/update/update.go

@@ -532,13 +532,20 @@ func (u *Updater) replaceBinaries(extractDir string) error {
 func (u *Updater) getInstallDirectories() []string {
 	dirs := []string{u.installDir}
 
-	// Also check cache directories where Claude Code looks for plugins
 	home, err := os.UserHomeDir()
 	if err != nil {
 		return dirs
 	}
 
-	// Look for cache directories under ~/.claude/plugins/cache/claude-mnemonic/claude-mnemonic/
+	// Primary stable binary location (survives Claude Code updates)
+	stableBin := filepath.Join(home, ".claude-mnemonic", "bin")
+	if stableBin != u.installDir {
+		if _, err := os.Stat(stableBin); err == nil {
+			dirs = append(dirs, stableBin)
+		}
+	}
+
+	// Also check cache directories where Claude Code looks for plugins
 	cacheBase := filepath.Join(home, ".claude/plugins/cache/claude-mnemonic/claude-mnemonic")
 	entries, err := os.ReadDir(cacheBase)
 	if err != nil {
@@ -548,7 +555,6 @@ func (u *Updater) getInstallDirectories() []string {
 	for _, entry := range entries {
 		if entry.IsDir() {
 			cacheDir := filepath.Join(cacheBase, entry.Name())
-			// Only add if it's different from installDir and contains a worker binary
 			if cacheDir != u.installDir {
 				workerPath := filepath.Join(cacheDir, "worker")
 				if _, err := os.Stat(workerPath); err == nil {

internal/vector/sqlitevec/client.go

@@ -145,20 +145,24 @@ func (c *Client) AddDocuments(ctx context.Context, docs []Document) error {
 		return nil
 	}
 
-	c.writeMu.Lock()
-	defer c.writeMu.Unlock()
-
-	// Generate embeddings for all documents
+	// Prepare texts for embedding
 	texts := make([]string, len(docs))
 	for i, doc := range docs {
 		texts[i] = doc.Content
 	}
 
-	embeddings, err := c.embedSvc.EmbedBatch(texts)
+	// Compute embeddings OUTSIDE the write lock for better concurrency.
+	// Embedding is ONNX inference (slow, mutex-protected internally) — holding
+	// writeMu during inference blocks all concurrent writes and reads.
+	embeddings, err := c.embedSvc.EmbedBatchWithContext(ctx, texts)
 	if err != nil {
 		return fmt.Errorf("generate embeddings: %w", err)
 	}
 
+	// Acquire write lock for DB operations only
+	c.writeMu.Lock()
+	defer c.writeMu.Unlock()
+
 	// Insert into vectors table with model version tracking
 	const insertQuery = `
 		INSERT OR REPLACE INTO vectors (doc_id, embedding, sqlite_id, doc_type, field_type, project, scope, model_version)
@@ -271,7 +275,7 @@ func (c *Client) Query(ctx context.Context, query string, limit int, where map[s
 	}
 
 	// Generate query embedding OUTSIDE the lock for better concurrency
-	queryEmb, err := c.getOrComputeEmbedding(query)
+	queryEmb, err := c.getOrComputeEmbedding(ctx, query)
 	if err != nil {
 		return nil, fmt.Errorf("embed query: %w", err)
 	}
@@ -282,8 +286,10 @@ func (c *Client) Query(ctx context.Context, query string, limit int, where map[s
 		return nil, fmt.Errorf("serialize query embedding: %w", err)
 	}
 
-	// Now acquire read lock for the actual DB query
-	c.readMu.RLock()
+	// Acquire read lock with context awareness to prevent indefinite blocking
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return nil, fmt.Errorf("acquire read lock: %w", err)
+	}
 	defer c.readMu.RUnlock()
 
 	// Build query with filters
@@ -485,7 +491,7 @@ func (c *Client) QueryBatch(ctx context.Context, queries []string, limit int, wh
 // Combines results from different field types and deduplicates by document ID.
 func (c *Client) QueryMultiField(ctx context.Context, query string, limit int, docType string, project string) ([]QueryResult, error) {
 	// Generate embedding once
-	queryEmb, err := c.getOrComputeEmbedding(query)
+	queryEmb, err := c.getOrComputeEmbedding(ctx, query)
 	if err != nil {
 		return nil, fmt.Errorf("embed query: %w", err)
 	}
@@ -496,7 +502,9 @@ func (c *Client) QueryMultiField(ctx context.Context, query string, limit int, d
 		return nil, fmt.Errorf("serialize query embedding: %w", err)
 	}
 
-	c.readMu.RLock()
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return nil, fmt.Errorf("acquire read lock: %w", err)
+	}
 	defer c.readMu.RUnlock()
 
 	// Query with field type aggregation - get best match per document
@@ -555,6 +563,28 @@ func (c *Client) QueryMultiField(ctx context.Context, query string, limit int, d
 	return results, rows.Err()
 }
 
+// acquireRLockWithContext acquires a read lock on mu, respecting ctx cancellation.
+// If ctx is cancelled while waiting for the lock, the goroutine that eventually
+// acquires it will release it immediately to prevent leaks.
+func acquireRLockWithContext(ctx context.Context, mu *sync.RWMutex) error {
+	acquired := make(chan struct{})
+	go func() {
+		mu.RLock()
+		close(acquired)
+	}()
+	select {
+	case <-acquired:
+		return nil
+	case <-ctx.Done():
+		// Goroutine may still acquire lock after ctx cancelled — must unlock
+		go func() {
+			<-acquired
+			mu.RUnlock()
+		}()
+		return ctx.Err()
+	}
+}
+
 // truncateString truncates a string to maxLen characters.
 func truncateString(s string, maxLen int) string {
 	if len(s) <= maxLen {
@@ -565,7 +595,9 @@ func truncateString(s string, maxLen int) string {
 
 // Count returns the total number of vectors in the store.
 func (c *Client) Count(ctx context.Context) (int64, error) {
-	c.readMu.RLock()
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return 0, fmt.Errorf("acquire read lock: %w", err)
+	}
 	defer c.readMu.RUnlock()
 
 	var count int64
@@ -586,7 +618,9 @@ func (c *Client) ModelVersion() string {
 // - The vectors table is empty
 // - Any vectors have a different model_version than the current model
 func (c *Client) NeedsRebuild(ctx context.Context) (bool, string) {
-	c.readMu.RLock()
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return false, ""
+	}
 	defer c.readMu.RUnlock()
 
 	currentModel := c.embedSvc.Version()
@@ -634,7 +668,9 @@ type StaleVectorInfo struct {
 // GetStaleVectors returns doc_ids of vectors with mismatched or null model versions.
 // This enables granular rebuild - only re-embedding documents that need updating.
 func (c *Client) GetStaleVectors(ctx context.Context) ([]StaleVectorInfo, error) {
-	c.readMu.RLock()
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return nil, fmt.Errorf("acquire read lock: %w", err)
+	}
 	defer c.readMu.RUnlock()
 
 	currentModel := c.embedSvc.Version()
@@ -692,7 +728,9 @@ type VectorHealthStats struct {
 
 // GetHealthStats returns comprehensive health statistics about the vector store.
 func (c *Client) GetHealthStats(ctx context.Context) (*VectorHealthStats, error) {
-	c.readMu.RLock()
+	if err := acquireRLockWithContext(ctx, &c.readMu); err != nil {
+		return nil, fmt.Errorf("acquire read lock: %w", err)
+	}
 	defer c.readMu.RUnlock()
 
 	stats := &VectorHealthStats{
@@ -856,7 +894,9 @@ func (c *Client) DeleteByObservationID(ctx context.Context, obsID int64) error {
 
 // getOrComputeEmbedding returns a cached embedding or computes a new one.
 // Uses singleflight to prevent duplicate concurrent computations for the same query.
-func (c *Client) getOrComputeEmbedding(query string) ([]float32, error) {
+// The context controls timeout on the embedding mutex acquisition -- if the ONNX model
+// hangs under CGO, callers can bail out instead of blocking forever.
+func (c *Client) getOrComputeEmbedding(ctx context.Context, query string) ([]float32, error) {
 	now := time.Now().UnixNano()
 
 	// Check cache first (read lock)
@@ -870,8 +910,10 @@ func (c *Client) getOrComputeEmbedding(query string) ([]float32, error) {
 	}
 	c.queryCacheMu.RUnlock()
 
-	// Cache miss - use singleflight to deduplicate concurrent embedding requests
-	result, err, _ := c.embeddingGroup.Do(query, func() (any, error) {
+	// Cache miss - use singleflight DoChan to deduplicate concurrent embedding requests.
+	// DoChan + select allows per-caller context cancellation: if a caller's context
+	// expires it can bail out without waiting for the shared computation to finish.
+	ch := c.embeddingGroup.DoChan(query, func() (any, error) {
 		// Double-check cache inside singleflight (another goroutine may have just cached it)
 		c.queryCacheMu.RLock()
 		if entry, ok := c.queryCache[query]; ok {
@@ -885,7 +927,9 @@ func (c *Client) getOrComputeEmbedding(query string) ([]float32, error) {
 		// Record cache miss
 		c.stats.embeddingMisses.Add(1)
 
-		// Compute embedding
+		// Compute embedding — use non-context Embed here because the singleflight
+		// result is shared across callers with different contexts. Per-caller
+		// cancellation is handled by the select below.
 		emb, err := c.embedSvc.Embed(query)
 		if err != nil {
 			return nil, err
@@ -933,10 +977,15 @@ func (c *Client) getOrComputeEmbedding(query string) ([]float32, error) {
 		return emb, nil
 	})
 
-	if err != nil {
-		return nil, err
+	select {
+	case res := <-ch:
+		if res.Err != nil {
+			return nil, res.Err
+		}
+		return res.Val.([]float32), nil
+	case <-ctx.Done():
+		return nil, ctx.Err()
 	}
-	return result.([]float32), nil
 }
 
 // ClearCache clears the embedding cache.

internal/vector/sqlitevec/client_test.go

@@ -3,9 +3,12 @@ package sqlitevec
 import (
 	"context"
 	"database/sql"
+	"fmt"
 	"os"
 	"path/filepath"
+	"sync"
 	"testing"
+	"time"
 
 	sqlite_vec "github.com/asg017/sqlite-vec-go-bindings/cgo"
 	"github.com/lukaszraczylo/claude-mnemonic/internal/embedding"
@@ -1901,3 +1904,251 @@ func TestExtractObservationIDs_GlobalScope(t *testing.T) {
 	assert.Len(t, ids, 1)
 	assert.Equal(t, int64(123), ids[0])
 }
+
+// =============================================================================
+// REGRESSION TESTS FOR acquireRLockWithContext (Fix #45)
+// =============================================================================
+
+// TestAcquireRLockWithContext_Cancel verifies that when a write lock is held
+// and the context times out, acquireRLockWithContext returns context.DeadlineExceeded
+// promptly and the cleanup goroutine eventually releases the lock.
+func TestAcquireRLockWithContext_Cancel(t *testing.T) {
+	var mu sync.RWMutex
+
+	// Hold write lock so any RLock() call blocks.
+	locked := make(chan struct{})
+	release := make(chan struct{})
+	go func() {
+		mu.Lock()
+		close(locked)
+		<-release
+		mu.Unlock()
+	}()
+	<-locked // write lock is held
+
+	// Context with a tight deadline — must expire before we release the write lock.
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	err := acquireRLockWithContext(ctx, &mu)
+	elapsed := time.Since(start)
+
+	assert.ErrorIs(t, err, context.DeadlineExceeded, "should return DeadlineExceeded")
+	assert.Less(t, elapsed, 200*time.Millisecond, "should return within ~100ms of deadline")
+
+	// Release the write lock so the cleanup goroutine can finish.
+	close(release)
+
+	// After the write lock is released the cleanup goroutine acquires+releases
+	// the RLock. Wait long enough for it to drain.
+	time.Sleep(100 * time.Millisecond)
+
+	// Now an uncontended RLock should succeed immediately.
+	ctx2 := context.Background()
+	err2 := acquireRLockWithContext(ctx2, &mu)
+	assert.NoError(t, err2, "should succeed when uncontended after cleanup")
+	if err2 == nil {
+		mu.RUnlock()
+	}
+}
+
+// TestAcquireRLockWithContext_Success verifies that an uncontended mutex is
+// acquired without error and can be properly unlocked.
+func TestAcquireRLockWithContext_Success(t *testing.T) {
+	var mu sync.RWMutex
+
+	err := acquireRLockWithContext(context.Background(), &mu)
+	assert.NoError(t, err, "should succeed on uncontended mutex")
+	if err == nil {
+		// Panics if not held — validates that the lock was actually taken.
+		mu.RUnlock()
+	}
+}
+
+// TestAcquireRLockWithContext_CleanupOnCancel verifies that when
+// acquireRLockWithContext returns an error due to context cancellation, the
+// cleanup goroutine eventually releases the RLock so the mutex can be write-
+// locked again without deadlock.
+func TestAcquireRLockWithContext_CleanupOnCancel(t *testing.T) {
+	var mu sync.RWMutex
+
+	// Hold write lock to force RLock to block.
+	release := make(chan struct{})
+	locked := make(chan struct{})
+	go func() {
+		mu.Lock()
+		close(locked)
+		<-release
+		mu.Unlock()
+	}()
+	<-locked
+
+	// Context cancels after 10ms — way before we release the write lock.
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	err := acquireRLockWithContext(ctx, &mu)
+	assert.Error(t, err, "should fail due to cancelled context")
+
+	// Release the write lock; the cleanup goroutine inside acquireRLockWithContext
+	// will now acquire the RLock and immediately release it.
+	close(release)
+
+	// Give the cleanup goroutine time to run.
+	time.Sleep(50 * time.Millisecond)
+
+	// Acquire a write lock — would deadlock if cleanup goroutine left an RLock
+	// dangling. Use a done channel and select to avoid hanging the test.
+	done := make(chan struct{})
+	go func() {
+		mu.Lock()
+		defer mu.Unlock()
+		close(done) //nolint:SA2001 // intentional: proves no deadlock from leaked RLock
+	}()
+
+	select {
+	case <-done:
+		// Success — write lock acquired without deadlock.
+	case <-time.After(2 * time.Second):
+		t.Fatal("write lock acquisition timed out: cleanup goroutine may have leaked an RLock")
+	}
+}
+
+// =============================================================================
+// REGRESSION TESTS FOR Fix #1: Embedding outside writeMu in AddDocuments
+// =============================================================================
+
+// TestAddDocuments_EmbeddingOutsideWriteLock verifies that AddDocuments does NOT
+// hold the write lock during embedding computation. A concurrent Query call
+// should complete quickly while AddDocuments is computing embeddings.
+func TestAddDocuments_EmbeddingOutsideWriteLock(t *testing.T) {
+	db, dbCleanup := testDB(t)
+	defer dbCleanup()
+
+	embedSvc, embedCleanup := testEmbeddingService(t)
+	defer embedCleanup()
+
+	client, err := NewClient(Config{DB: db}, embedSvc)
+	require.NoError(t, err)
+
+	// Seed the DB with one document so Query has something to search
+	seedDocs := []Document{
+		{ID: "seed-1", Content: "Seed document for concurrency test"},
+	}
+	err = client.AddDocuments(context.Background(), seedDocs)
+	require.NoError(t, err)
+
+	// Pre-warm the embedding cache for the query text so the Query call
+	// itself doesn't need the embedding mutex — it only needs the DB read lock.
+	_, err = client.Query(context.Background(), "concurrency test", 5, nil)
+	require.NoError(t, err)
+
+	// Prepare a batch of documents to trigger a slow AddDocuments call
+	batchDocs := make([]Document, 10)
+	for i := range batchDocs {
+		batchDocs[i] = Document{
+			ID:      fmt.Sprintf("batch-%d", i),
+			Content: fmt.Sprintf("Batch document number %d for write lock test with unique content", i),
+		}
+	}
+
+	// Launch AddDocuments in background — embedding will take time
+	addDone := make(chan error, 1)
+	go func() {
+		addDone <- client.AddDocuments(context.Background(), batchDocs)
+	}()
+
+	// Give AddDocuments a moment to start embedding computation
+	time.Sleep(10 * time.Millisecond)
+
+	// Invalidate result cache so Query must go through to DB (tests read lock)
+	client.InvalidateResultCache()
+
+	// A concurrent Query should NOT be blocked by AddDocuments.
+	// If the old code held writeMu during embedding, this would block until
+	// embedding finishes. With the fix, it should complete quickly.
+	queryCtx, queryCancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer queryCancel()
+
+	start := time.Now()
+	_, err = client.Query(queryCtx, "concurrency test", 5, nil)
+	queryDuration := time.Since(start)
+
+	require.NoError(t, err, "Query should succeed while AddDocuments is embedding")
+	// The query should complete well within the timeout if writeMu is not held
+	assert.Less(t, queryDuration, 1*time.Second,
+		"Query should complete quickly when writeMu is not held during embedding")
+
+	// Wait for AddDocuments to finish
+	err = <-addDone
+	require.NoError(t, err, "AddDocuments should succeed")
+}
+
+// =============================================================================
+// REGRESSION TESTS FOR Fix #2a: DoChan + context select in getOrComputeEmbedding
+// =============================================================================
+
+// TestGetOrComputeEmbedding_ContextCancelDuringSingleflight verifies that when
+// a singleflight embedding computation is in progress, a second caller with a
+// short-lived context returns context.DeadlineExceeded promptly rather than
+// waiting for the slow first call to finish.
+func TestGetOrComputeEmbedding_ContextCancelDuringSingleflight(t *testing.T) {
+	db, dbCleanup := testDB(t)
+	defer dbCleanup()
+
+	embedSvc, embedCleanup := testEmbeddingService(t)
+	defer embedCleanup()
+
+	client, err := NewClient(Config{DB: db}, embedSvc)
+	require.NoError(t, err)
+
+	// Add a document so we can query
+	docs := []Document{
+		{ID: "sf-test-1", Content: "Singleflight context cancellation test document"},
+	}
+	err = client.AddDocuments(context.Background(), docs)
+	require.NoError(t, err)
+
+	// Clear cache to force embedding computation
+	client.ClearCache()
+	client.InvalidateResultCache()
+
+	queryText := "unique singleflight context test query"
+
+	// First call: start a normal query in background (will trigger singleflight)
+	firstDone := make(chan struct{})
+	go func() {
+		defer close(firstDone)
+		_, _ = client.Query(context.Background(), queryText, 5, nil)
+	}()
+
+	// Give the first call a moment to start the singleflight computation
+	time.Sleep(5 * time.Millisecond)
+
+	// Second call: use a very short context that should expire quickly
+	shortCtx, shortCancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	defer shortCancel()
+
+	// Clear result cache again so the second call hits getOrComputeEmbedding
+	client.InvalidateResultCache()
+
+	start := time.Now()
+	_, err = client.Query(shortCtx, queryText, 5, nil)
+	elapsed := time.Since(start)
+
+	// With DoChan + select, the second caller should return quickly with context error.
+	// Note: If the embedding completes fast enough, the second call may succeed
+	// via singleflight sharing. That's also valid — the test primarily checks
+	// that it doesn't BLOCK for the full embedding duration on context cancel.
+	if err != nil {
+		assert.ErrorIs(t, err, context.DeadlineExceeded,
+			"Should return DeadlineExceeded when context expires during singleflight")
+		assert.Less(t, elapsed, 500*time.Millisecond,
+			"Should return promptly on context cancellation, not wait for slow computation")
+	}
+	// If err == nil, the singleflight completed before the context expired — also valid.
+
+	// Wait for first call to finish
+	<-firstDone
+}

internal/watcher/watcher_test.go

@@ -0,0 +1,416 @@
+//go:build fts5
+
+package watcher
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// waitForCondition polls fn every 10ms until it returns true or timeout expires.
+func waitForCondition(t *testing.T, timeout time.Duration, fn func() bool) bool {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if fn() {
+			return true
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	return false
+}
+
+// TestNew_CreatesWatcherWithCorrectFields verifies New initialises all fields correctly.
+func TestNew_CreatesWatcherWithCorrectFields(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	called := false
+	cb := func() { called = true }
+
+	w, err := New(target, cb)
+	require.NoError(t, err)
+	require.NotNil(t, w)
+	defer w.Stop() //nolint:errcheck
+
+	assert.Equal(t, target, w.targetPath)
+	assert.Equal(t, dir, w.parentPath)
+	assert.Equal(t, 100*time.Millisecond, w.debounce)
+	assert.NotNil(t, w.watcher)
+	assert.NotNil(t, w.ctx)
+	assert.NotNil(t, w.cancel)
+	assert.False(t, w.running)
+	assert.False(t, called, "callback must not be invoked on creation")
+}
+
+// TestNew_NilCallback is valid — handleDeletion guards for nil onDelete.
+func TestNew_NilCallback(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, nil)
+	require.NoError(t, err)
+	require.NotNil(t, w)
+	defer w.Stop() //nolint:errcheck
+
+	assert.Nil(t, w.onDelete)
+}
+
+// TestStart_SetsRunningTrue verifies Start transitions running to true.
+func TestStart_SetsRunningTrue(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	err = w.Start()
+	require.NoError(t, err)
+
+	w.mu.Lock()
+	running := w.running
+	w.mu.Unlock()
+	assert.True(t, running)
+}
+
+// TestStart_Idempotent verifies calling Start twice does not panic or return error.
+func TestStart_Idempotent(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+	require.NoError(t, w.Start(), "second Start must be a no-op without error")
+
+	// Still only one goroutine running — running flag is still true.
+	w.mu.Lock()
+	running := w.running
+	w.mu.Unlock()
+	assert.True(t, running)
+}
+
+// TestStop_SetsRunningFalse verifies Stop transitions running to false.
+func TestStop_SetsRunningFalse(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+
+	require.NoError(t, w.Start())
+	require.NoError(t, w.Stop())
+
+	w.mu.Lock()
+	running := w.running
+	w.mu.Unlock()
+	assert.False(t, running)
+}
+
+// TestStop_Idempotent verifies calling Stop when not running returns nil.
+func TestStop_Idempotent(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+
+	// Never started — Stop must be a no-op.
+	assert.NoError(t, w.Stop())
+	// Second stop after the first no-op must also succeed.
+	assert.NoError(t, w.Stop())
+}
+
+// TestStop_WithoutStart verifies Stop on an unstarted watcher is safe.
+func TestStop_WithoutStart(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+
+	err = w.Stop()
+	assert.NoError(t, err)
+}
+
+// TestTargetDeletion_CallbackFired verifies that deleting the target file triggers onDelete.
+func TestTargetDeletion_CallbackFired(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	// Create the target file so the parent watch is real.
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+
+	// Delete the target file.
+	require.NoError(t, os.Remove(target))
+
+	// Wait up to 1 second for the debounced callback (debounce=100ms).
+	fired := waitForCondition(t, 1*time.Second, func() bool {
+		return atomic.LoadInt32(&callCount) > 0
+	})
+	assert.True(t, fired, "onDelete callback not called after target deletion")
+}
+
+// TestTargetDeletion_CallbackCalledOnce verifies debounce suppresses duplicate events.
+func TestTargetDeletion_CallbackCalledOnce(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+
+	require.NoError(t, os.Remove(target))
+
+	// Wait for callback to fire.
+	waitForCondition(t, 1*time.Second, func() bool {
+		return atomic.LoadInt32(&callCount) > 0
+	})
+
+	// Wait an extra debounce window to confirm no second call arrives.
+	time.Sleep(300 * time.Millisecond)
+	assert.Equal(t, int32(1), atomic.LoadInt32(&callCount), "callback fired more than once for a single deletion")
+}
+
+// TestTargetRecreation_CancelsCallback verifies that recreating the target before the
+// debounce fires suppresses the onDelete callback.
+func TestTargetRecreation_CancelsCallback(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	// Use a longer debounce so we can recreate before it fires.
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	// Override debounce to give us a larger window.
+	w.debounce = 300 * time.Millisecond
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+
+	// Delete then immediately recreate within the debounce window.
+	require.NoError(t, os.Remove(target))
+	time.Sleep(20 * time.Millisecond) // ensure delete event is processed
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	// Wait past full debounce period to confirm callback was cancelled.
+	time.Sleep(500 * time.Millisecond)
+	assert.Equal(t, int32(0), atomic.LoadInt32(&callCount), "callback should have been cancelled by recreation")
+}
+
+// TestParentDirectoryDeletion_CallbackFired verifies that deleting the parent directory
+// triggers the onDelete callback.
+func TestParentDirectoryDeletion_CallbackFired(t *testing.T) {
+	// Create a nested structure: base/sub/db.sqlite so we can remove sub
+	// without losing t.TempDir (which is base).
+	base := t.TempDir()
+	sub := filepath.Join(base, "sub")
+	require.NoError(t, os.Mkdir(sub, 0o755))
+	target := filepath.Join(sub, "db.sqlite")
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+
+	// Remove parent directory entirely.
+	require.NoError(t, os.RemoveAll(sub))
+
+	fired := waitForCondition(t, 1500*time.Millisecond, func() bool {
+		return atomic.LoadInt32(&callCount) > 0
+	})
+	assert.True(t, fired, "onDelete callback not called after parent directory deletion")
+}
+
+// TestAddWatch_NonExistentParent verifies addWatch returns an error when parent is absent.
+func TestAddWatch_NonExistentParent(t *testing.T) {
+	// Point watcher at a path whose parent definitely does not exist.
+	nonExistent := filepath.Join(t.TempDir(), "missing", "db.sqlite")
+
+	w, err := New(nonExistent, func() {})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	err = w.addWatch()
+	assert.Error(t, err, "addWatch must fail when parent directory does not exist")
+}
+
+// TestContextCancellation_StopsWatchLoop verifies the watchLoop exits when Stop is called.
+func TestContextCancellation_StopsWatchLoop(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+
+	require.NoError(t, w.Start())
+
+	// Stop cancels the context; the goroutine should exit cleanly.
+	require.NoError(t, w.Stop())
+
+	// Give the goroutine a moment to exit — then verify running is false.
+	time.Sleep(50 * time.Millisecond)
+	w.mu.Lock()
+	running := w.running
+	w.mu.Unlock()
+	assert.False(t, running)
+}
+
+// TestParentDirRecreation_ReEstablishesWatch verifies that recreating the parent after
+// deletion allows subsequent target-deletion events to fire the callback.
+func TestParentDirRecreation_ReEstablishesWatch(t *testing.T) {
+	base := t.TempDir()
+	sub := filepath.Join(base, "sub")
+	require.NoError(t, os.Mkdir(sub, 0o755))
+	target := filepath.Join(sub, "db.sqlite")
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+
+	require.NoError(t, w.Start())
+
+	// Remove the parent.
+	require.NoError(t, os.RemoveAll(sub))
+
+	// Wait for first callback.
+	fired := waitForCondition(t, 1500*time.Millisecond, func() bool {
+		return atomic.LoadInt32(&callCount) > 0
+	})
+	require.True(t, fired, "first deletion callback must fire")
+
+	firstCount := atomic.LoadInt32(&callCount)
+
+	// Recreate parent and target — re-established watch should allow a second callback.
+	require.NoError(t, os.Mkdir(sub, 0o755))
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	// Wait for handleDeletion's goroutine to attempt re-adding the watch (500ms sleep inside).
+	time.Sleep(700 * time.Millisecond)
+
+	// Now delete the target again.
+	require.NoError(t, os.Remove(target))
+
+	// We only assert the first callback fired; the re-watch is best-effort and
+	// OS-timing-dependent, so we don't hard-assert a second callback.
+	assert.GreaterOrEqual(t, atomic.LoadInt32(&callCount), firstCount, "call count must not decrease")
+}
+
+// TestConcurrentStartStop verifies that concurrent Start/Stop calls do not race or panic.
+func TestConcurrentStartStop(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+
+	w, err := New(target, func() {})
+	require.NoError(t, err)
+
+	var wg sync.WaitGroup
+	ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+	defer cancel()
+
+	// Launch goroutines that repeatedly start/stop the watcher.
+	for i := 0; i < 5; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for {
+				select {
+				case <-ctx.Done():
+					return
+				default:
+					_ = w.Start()
+					time.Sleep(5 * time.Millisecond)
+					_ = w.Stop()
+					time.Sleep(5 * time.Millisecond)
+				}
+			}
+		}()
+	}
+	wg.Wait()
+	// No panic = pass. Final state: running should be consistent (we don't assert
+	// a specific value since Stop may have won last).
+}
+
+// TestDebounceField_DefaultValue asserts the default debounce is 100ms.
+func TestDebounceField_DefaultValue(t *testing.T) {
+	dir := t.TempDir()
+	w, err := New(filepath.Join(dir, "x"), func() {})
+	require.NoError(t, err)
+	defer w.Stop() //nolint:errcheck
+	assert.Equal(t, 100*time.Millisecond, w.debounce)
+}
+
+// TestCallbackNotCalledWhenStopped verifies that if we Stop before the debounce fires,
+// the callback is not invoked after Stop (context cancel exits the watchLoop).
+func TestCallbackNotCalledWhenStopped(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "db.sqlite")
+	require.NoError(t, os.WriteFile(target, []byte("data"), 0o644))
+
+	var callCount int32
+	w, err := New(target, func() {
+		atomic.AddInt32(&callCount, 1)
+	})
+	require.NoError(t, err)
+	w.debounce = 500 * time.Millisecond // wide window
+
+	require.NoError(t, w.Start())
+
+	// Delete file — debounce timer is now running (500ms).
+	require.NoError(t, os.Remove(target))
+	time.Sleep(20 * time.Millisecond) // let event propagate
+
+	// Stop before timer fires — context is cancelled, watchLoop exits.
+	require.NoError(t, w.Stop())
+
+	// Wait past the debounce window; the AfterFunc may still fire (it's not
+	// tied to the context), but the watcher is stopped. We assert the loop
+	// itself exited cleanly.
+	time.Sleep(700 * time.Millisecond)
+
+	// The AfterFunc timer fires outside the watchLoop — callback may or may not
+	// have fired depending on OS scheduling. We assert no panic occurred.
+	// The important invariant: running is false.
+	w.mu.Lock()
+	running := w.running
+	w.mu.Unlock()
+	assert.False(t, running)
+}

internal/worker/handlers.go

@@ -13,6 +13,7 @@ import (
 	"fmt"
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/rs/zerolog/log"
 )
@@ -142,19 +143,55 @@ func formatWarning(format string, args ...any) string {
 }
 
 // handleHealth handles health check requests.
-// Returns 200 OK immediately (even during init) so hooks can connect quickly.
-// Use /api/ready for full readiness check.
+// Returns 200 when ready, 503 when initializing or degraded.
 func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
-	status := "starting"
-	if s.ready.Load() {
-		status = "ready"
-	} else if err := s.GetInitError(); err != nil {
-		status = "error"
+	status := "ready"
+	dbStatus := "ok"
+	embeddingStatus := "ok"
+
+	if !s.ready.Load() {
+		status = "initializing"
+		if err := s.GetInitError(); err != nil {
+			status = "error"
+		}
 	}
-	writeJSON(w, map[string]any{
-		"status":  status,
-		"version": s.version,
-	})
+
+	// Check embedding service
+	if s.embedSvc == nil {
+		embeddingStatus = "unavailable"
+		if status == "ready" {
+			status = "degraded"
+		}
+	}
+
+	// Check DB
+	if s.store == nil {
+		dbStatus = "unavailable"
+		if status == "ready" {
+			status = "degraded"
+		}
+	}
+
+	activeSessions := 0
+	if s.sessionManager != nil {
+		activeSessions = s.sessionManager.GetActiveSessionCount()
+	}
+
+	resp := map[string]any{
+		"status":           status,
+		"ready":            s.ready.Load(),
+		"uptime_seconds":   int(time.Since(s.startTime).Seconds()),
+		"active_sessions":  activeSessions,
+		"db_status":        dbStatus,
+		"embedding_status": embeddingStatus,
+		"version":          s.version,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	if status != "ready" {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}
+	json.NewEncoder(w).Encode(resp)
 }
 
 // handleVersion returns the worker version for version checking.

internal/worker/handlers_context.go

@@ -23,6 +23,10 @@ import (
 // IMPORTANT: This is on the critical startup path - must be fast!
 // No synchronous verification - just filter by staleness and return.
 func (s *Service) handleSearchByPrompt(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	project := r.URL.Query().Get("project")
 	query := r.URL.Query().Get("query")
 	cwd := r.URL.Query().Get("cwd")
@@ -54,7 +58,7 @@ func (s *Service) handleSearchByPrompt(w http.ResponseWriter, r *http.Request) {
 	var expandedQueries []expansion.ExpandedQuery
 	var detectedIntent string
 	if s.queryExpander != nil {
-		expandCtx, expandCancel := context.WithTimeout(r.Context(), 5*time.Second)
+		expandCtx, expandCancel := context.WithTimeout(ctx, 5*time.Second)
 		cfg := expansion.DefaultConfig()
 		cfg.EnableVocabularyExpansion = false // Vocabulary expansion is optional
 		expandedQueries = s.queryExpander.Expand(expandCtx, query, cfg)
@@ -83,7 +87,7 @@ func (s *Service) handleSearchByPrompt(w http.ResponseWriter, r *http.Request) {
 		var vectorErrors int
 
 		for _, eq := range expandedQueries {
-			vectorResults, vecErr := s.vectorClient.Query(r.Context(), eq.Query, limit*2, where)
+			vectorResults, vecErr := s.vectorClient.Query(ctx, eq.Query, limit*2, where)
 			if vecErr != nil {
 				vectorErrors++
 				log.Debug().Err(vecErr).Str("query", eq.Query).Msg("Vector query failed")
@@ -125,7 +129,7 @@ func (s *Service) handleSearchByPrompt(w http.ResponseWriter, r *http.Request) {
 
 			if len(obsIDs) > 0 {
 				// Fetch full observations from SQLite
-				observations, err = s.observationStore.GetObservationsByIDs(r.Context(), obsIDs, "date_desc", limit)
+				observations, err = s.observationStore.GetObservationsByIDs(ctx, obsIDs, "date_desc", limit)
 				if err == nil {
 					usedVector = true
 				}
@@ -138,11 +142,11 @@ func (s *Service) handleSearchByPrompt(w http.ResponseWriter, r *http.Request) {
 		if vectorSearchFailed {
 			log.Info().Str("project", project).Msg("Using FTS fallback due to vector search failure")
 		}
-		observations, err = s.observationStore.SearchObservationsFTS(r.Context(), query, project, limit)
+		observations, err = s.observationStore.SearchObservationsFTS(ctx, query, project, limit)
 		if err != nil {
 			// FTS might fail if query has special chars, try without
 			log.Warn().Err(err).Str("query", query).Msg("FTS search failed, falling back to recent")
-			observations, err = s.observationStore.GetRecentObservations(r.Context(), project, limit)
+			observations, err = s.observationStore.GetRecentObservations(ctx, project, limit)
 			if err != nil {
 				http.Error(w, err.Error(), http.StatusInternalServerError)
 				return
@@ -354,7 +358,9 @@ func (s *Service) handleFileContext(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Search for observations related to each file in parallel
-	ctx := r.Context()
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, ctxCancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer ctxCancel()
 
 	// Check if vector search is available
 	if s.vectorClient == nil || !s.vectorClient.IsConnected() {
@@ -562,6 +568,10 @@ func splitCamelCase(s string) string {
 // IMPORTANT: This is on the critical startup path - must be fast!
 // No synchronous verification - just filter by staleness and return.
 func (s *Service) handleContextInject(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	project := r.URL.Query().Get("project")
 	if project == "" {
 		http.Error(w, "project required", http.StatusBadRequest)
@@ -592,7 +602,7 @@ func (s *Service) handleContextInject(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Get recent observations
-	observations, err := s.observationStore.GetRecentObservations(r.Context(), project, limit)
+	observations, err := s.observationStore.GetRecentObservations(ctx, project, limit)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
@@ -658,13 +668,17 @@ func (s *Service) handleContextInject(w http.ResponseWriter, r *http.Request) {
 
 // handleContextCount returns the count of observations for a project.
 func (s *Service) handleContextCount(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	project := r.URL.Query().Get("project")
 	if project == "" {
 		http.Error(w, "project required", http.StatusBadRequest)
 		return
 	}
 
-	count, err := s.getCachedObservationCount(r.Context(), project)
+	count, err := s.getCachedObservationCount(ctx, project)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return

internal/worker/handlers_data.go

@@ -2,6 +2,7 @@
 package worker
 
 import (
+	"context"
 	"encoding/json"
 	"net/http"
 	"runtime"
@@ -20,6 +21,10 @@ import (
 // Supports optional query parameter for semantic search via sqlite-vec.
 // Supports pagination via limit and offset query parameters.
 func (s *Service) handleGetObservations(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	pagination := gorm.ParsePaginationParams(r, DefaultObservationsLimit)
 	project := r.URL.Query().Get("project")
 	query := r.URL.Query().Get("query")
@@ -38,11 +43,11 @@ func (s *Service) handleGetObservations(w http.ResponseWriter, r *http.Request)
 	// Use vector search if query is provided and vector client is available
 	if query != "" && s.vectorClient != nil && s.vectorClient.IsConnected() {
 		where := sqlitevec.BuildWhereFilter(sqlitevec.DocTypeObservation, "")
-		vectorResults, vecErr := s.vectorClient.Query(r.Context(), query, pagination.Limit*2, where)
+		vectorResults, vecErr := s.vectorClient.Query(ctx, query, pagination.Limit*2, where)
 		if vecErr == nil && len(vectorResults) > 0 {
 			obsIDs := sqlitevec.ExtractObservationIDs(vectorResults, project)
 			if len(obsIDs) > 0 {
-				observations, err = s.observationStore.GetObservationsByIDs(r.Context(), obsIDs, "date_desc", pagination.Limit)
+				observations, err = s.observationStore.GetObservationsByIDs(ctx, obsIDs, "date_desc", pagination.Limit)
 				if err == nil {
 					usedVector = true
 					total = int64(len(observations)) // Vector search doesn't have total, use returned count
@@ -55,10 +60,10 @@ func (s *Service) handleGetObservations(w http.ResponseWriter, r *http.Request)
 	if !usedVector {
 		if project != "" {
 			// Strict project filtering for dashboard - only observations from this project
-			observations, total, err = s.observationStore.GetObservationsByProjectStrictPaginated(r.Context(), project, pagination.Limit, pagination.Offset)
+			observations, total, err = s.observationStore.GetObservationsByProjectStrictPaginated(ctx, project, pagination.Limit, pagination.Offset)
 		} else {
 			// All projects
-			observations, total, err = s.observationStore.GetAllRecentObservationsPaginated(r.Context(), pagination.Limit, pagination.Offset)
+			observations, total, err = s.observationStore.GetAllRecentObservationsPaginated(ctx, pagination.Limit, pagination.Offset)
 		}
 	}
 
@@ -90,6 +95,10 @@ func (s *Service) handleGetObservations(w http.ResponseWriter, r *http.Request)
 // handleGetSummaries returns recent summaries.
 // Supports optional query parameter for semantic search via sqlite-vec.
 func (s *Service) handleGetSummaries(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	limit := gorm.ParseLimitParam(r, DefaultSummariesLimit)
 	project := r.URL.Query().Get("project")
 	query := r.URL.Query().Get("query")
@@ -107,11 +116,11 @@ func (s *Service) handleGetSummaries(w http.ResponseWriter, r *http.Request) {
 	// Use vector search if query is provided and vector client is available
 	if query != "" && s.vectorClient != nil && s.vectorClient.IsConnected() {
 		where := sqlitevec.BuildWhereFilter(sqlitevec.DocTypeSessionSummary, "")
-		vectorResults, vecErr := s.vectorClient.Query(r.Context(), query, limit*2, where)
+		vectorResults, vecErr := s.vectorClient.Query(ctx, query, limit*2, where)
 		if vecErr == nil && len(vectorResults) > 0 {
 			summaryIDs := sqlitevec.ExtractSummaryIDs(vectorResults, project)
 			if len(summaryIDs) > 0 {
-				summaries, err = s.summaryStore.GetSummariesByIDs(r.Context(), summaryIDs, "date_desc", limit)
+				summaries, err = s.summaryStore.GetSummariesByIDs(ctx, summaryIDs, "date_desc", limit)
 				if err == nil {
 					usedVector = true
 				}
@@ -122,9 +131,9 @@ func (s *Service) handleGetSummaries(w http.ResponseWriter, r *http.Request) {
 	// Fall back to SQLite if vector search not used
 	if !usedVector {
 		if project != "" {
-			summaries, err = s.summaryStore.GetRecentSummaries(r.Context(), project, limit)
+			summaries, err = s.summaryStore.GetRecentSummaries(ctx, project, limit)
 		} else {
-			summaries, err = s.summaryStore.GetAllRecentSummaries(r.Context(), limit)
+			summaries, err = s.summaryStore.GetAllRecentSummaries(ctx, limit)
 		}
 	}
 
@@ -143,6 +152,10 @@ func (s *Service) handleGetSummaries(w http.ResponseWriter, r *http.Request) {
 // handleGetPrompts returns recent user prompts.
 // Supports optional query parameter for semantic search via sqlite-vec.
 func (s *Service) handleGetPrompts(w http.ResponseWriter, r *http.Request) {
+	// Add request-scoped timeout to prevent indefinite blocking on DB operations
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
 	limit := gorm.ParseLimitParam(r, DefaultPromptsLimit)
 	project := r.URL.Query().Get("project")
 	query := r.URL.Query().Get("query")
@@ -160,11 +173,11 @@ func (s *Service) handleGetPrompts(w http.ResponseWriter, r *http.Request) {
 	// Use vector search if query is provided and vector client is available
 	if query != "" && s.vectorClient != nil && s.vectorClient.IsConnected() {
 		where := sqlitevec.BuildWhereFilter(sqlitevec.DocTypeUserPrompt, "")
-		vectorResults, vecErr := s.vectorClient.Query(r.Context(), query, limit*2, where)
+		vectorResults, vecErr := s.vectorClient.Query(ctx, query, limit*2, where)
 		if vecErr == nil && len(vectorResults) > 0 {
 			promptIDs := sqlitevec.ExtractPromptIDs(vectorResults, project)
 			if len(promptIDs) > 0 {
-				prompts, err = s.promptStore.GetPromptsByIDs(r.Context(), promptIDs, "date_desc", limit)
+				prompts, err = s.promptStore.GetPromptsByIDs(ctx, promptIDs, "date_desc", limit)
 				if err == nil {
 					usedVector = true
 				}
@@ -175,9 +188,9 @@ func (s *Service) handleGetPrompts(w http.ResponseWriter, r *http.Request) {
 	// Fall back to SQLite if vector search not used
 	if !usedVector {
 		if project != "" {
-			prompts, err = s.promptStore.GetRecentUserPromptsByProject(r.Context(), project, limit)
+			prompts, err = s.promptStore.GetRecentUserPromptsByProject(ctx, project, limit)
 		} else {
-			prompts, err = s.promptStore.GetAllRecentUserPrompts(r.Context(), limit)
+			prompts, err = s.promptStore.GetAllRecentUserPrompts(ctx, limit)
 		}
 	}
 

internal/worker/handlers_relations.go

@@ -46,7 +46,7 @@ func (s *Service) handleGetRelationGraph(w http.ResponseWriter, r *http.Request)
 	// Get depth parameter (default 2)
 	depth := 2
 	if depthStr := r.URL.Query().Get("depth"); depthStr != "" {
-		if d, err := strconv.Atoi(depthStr); err == nil && d > 0 && d <= 5 {
+		if d, parseErr := strconv.Atoi(depthStr); parseErr == nil && d > 0 && d <= 5 {
 			depth = d
 		}
 	}
@@ -72,7 +72,7 @@ func (s *Service) handleGetRelatedObservations(w http.ResponseWriter, r *http.Re
 	// Get minimum confidence parameter (default 0.4)
 	minConfidence := 0.4
 	if confStr := r.URL.Query().Get("min_confidence"); confStr != "" {
-		if c, err := strconv.ParseFloat(confStr, 64); err == nil && c >= 0 && c <= 1 {
+		if c, parseErr := strconv.ParseFloat(confStr, 64); parseErr == nil && c >= 0 && c <= 1 {
 			minConfidence = c
 		}
 	}

internal/worker/handlers_scoring.go

@@ -42,11 +42,9 @@ func (s *Service) handleObservationFeedback(w http.ResponseWriter, r *http.Reque
 		return
 	}
 
-	// Get required components
-	s.initMu.RLock()
+	// Get required components (initMu.RLock held by requireReady middleware)
 	observationStore := s.observationStore
 	scoreCalculator := s.scoreCalculator
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -95,10 +93,9 @@ func (s *Service) handleObservationFeedback(w http.ResponseWriter, r *http.Reque
 func (s *Service) handleGetScoringStats(w http.ResponseWriter, r *http.Request) {
 	project := r.URL.Query().Get("project")
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
 	recalculator := s.recalculator
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -130,9 +127,8 @@ func (s *Service) handleGetTopObservations(w http.ResponseWriter, r *http.Reques
 	limit := parseIntParam(r, "limit", 10)
 	project := r.URL.Query().Get("project")
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -158,9 +154,8 @@ func (s *Service) handleGetMostRetrieved(w http.ResponseWriter, r *http.Request)
 	limit := parseIntParam(r, "limit", 10)
 	project := r.URL.Query().Get("project")
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -191,10 +186,9 @@ func (s *Service) handleExplainScore(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
 	scoreCalculator := s.scoreCalculator
-	s.initMu.RUnlock()
 
 	if observationStore == nil || scoreCalculator == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -245,10 +239,9 @@ func (s *Service) handleUpdateConceptWeight(w http.ResponseWriter, r *http.Reque
 		return
 	}
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
 	recalculator := s.recalculator
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -279,9 +272,8 @@ func (s *Service) handleUpdateConceptWeight(w http.ResponseWriter, r *http.Reque
 // handleGetConceptWeights returns all concept weights.
 // GET /api/scoring/concepts
 func (s *Service) handleGetConceptWeights(w http.ResponseWriter, r *http.Request) {
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	observationStore := s.observationStore
-	s.initMu.RUnlock()
 
 	if observationStore == nil {
 		http.Error(w, "service not ready", http.StatusServiceUnavailable)
@@ -300,19 +292,22 @@ func (s *Service) handleGetConceptWeights(w http.ResponseWriter, r *http.Request
 // handleTriggerRecalculation triggers an immediate score recalculation.
 // POST /api/scoring/recalculate
 func (s *Service) handleTriggerRecalculation(w http.ResponseWriter, r *http.Request) {
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware
 	recalculator := s.recalculator
-	s.initMu.RUnlock()
 
 	if recalculator == nil {
 		http.Error(w, "recalculator not available", http.StatusServiceUnavailable)
 		return
 	}
 
-	// Run recalculation in background
+	// Run recalculation in background with independent context
+	s.wg.Add(1)
 	go func() {
-		if err := recalculator.RecalculateNow(r.Context()); err != nil {
-			log.Warn().Err(err).Msg("Background score recalculation failed")
+		defer s.wg.Done()
+		ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+		defer cancel()
+		if err := recalculator.RecalculateNow(ctx); err != nil {
+			log.Error().Err(err).Msg("Background recalculation failed")
 		}
 	}()
 
@@ -336,27 +331,24 @@ func (s *Service) incrementRetrievalCounts(ids []int64) {
 		return
 	}
 
-	s.initMu.RLock()
+	// initMu.RLock held by requireReady middleware (caller is always behind requireReady)
 	store := s.observationStore
-	s.initMu.RUnlock()
 
 	if store == nil {
 		return
 	}
 
 	// Increment in background to not block response
-	// Use service context to respect shutdown signals
 	s.wg.Add(1)
 	go func() {
 		defer s.wg.Done()
-		ctx, cancel := context.WithTimeout(s.ctx, 3*time.Second)
+		// Create a new context with timeout for the background operation
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
 		defer cancel()
 
 		if err := store.IncrementRetrievalCount(ctx, ids); err != nil {
 			// Log but don't fail - this is a background operation
-			if s.ctx.Err() == nil { // Don't log during shutdown
-				log.Debug().Err(err).Msg("Failed to increment retrieval counts")
-			}
+			_ = err // Explicitly ignore - background operation
 		}
 	}()
 }

internal/worker/handlers_sessions.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -44,7 +45,30 @@ func (s *Service) handleSessionInit(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
+	// Reject requests from internal CLI calls (callClaudeCLI runs from /tmp with no session ID).
+	// These are the memory extraction agent's own prompts, not real user prompts.
+	if req.ClaudeSessionID == "" {
+		log.Debug().Str("project", req.Project).Msg("Rejecting session init with empty claude session ID (internal call)")
+		writeJSON(w, SessionInitResponse{
+			Skipped: true,
+			Reason:  "internal",
+		})
+		return
+	}
 
+	// Reject prompts that contain the internal system prompt (from SDK processor).
+	// The SDK processor sets CLAUDE_MNEMONIC_INTERNAL=1 on the subprocess env,
+	// but Claude Code does NOT propagate custom env vars to hook subprocesses,
+	// so that guard fails and the system prompt leaks into the database as a
+	// regular user prompt. This server-side check catches those cases reliably.
+	if strings.Contains(req.Prompt, "You are a memory extraction agent for Claude Code sessions") {
+		log.Debug().Str("project", req.Project).Msg("Rejecting session init with internal system prompt")
+		writeJSON(w, SessionInitResponse{
+			Skipped: true,
+			Reason:  "internal",
+		})
+		return
+	}
 	// Privacy check
 	if privacy.IsEntirelyPrivate(req.Prompt) {
 		// Create session but skip processing
@@ -84,6 +108,24 @@ func (s *Service) handleSessionInit(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// CROSS-SESSION DUPLICATE DETECTION: Same prompt text from ANY session within the window.
+	// This catches duplicates when the SDK processor's callClaudeCLI subprocess fires
+	// UserPromptSubmit with a different Claude session ID than the original hook.
+	if _, existingNum, found := s.promptStore.FindRecentPromptByTextGlobal(r.Context(), cleanedPrompt, DuplicatePromptWindowSeconds); found {
+		sessionID, _ := s.sessionStore.CreateSDKSession(r.Context(), req.ClaudeSessionID, req.Project, cleanedPrompt)
+
+		log.Debug().
+			Int64("sessionId", sessionID).
+			Int("promptNumber", existingNum).
+			Msg("Cross-session duplicate prompt detected")
+
+		writeJSON(w, SessionInitResponse{
+			SessionDBID:  sessionID,
+			PromptNumber: existingNum,
+		})
+		return
+	}
+
 	// Create session (idempotent)
 	sessionID, err := s.sessionStore.CreateSDKSession(r.Context(), req.ClaudeSessionID, req.Project, cleanedPrompt)
 	if err != nil {
@@ -210,6 +252,12 @@ func (s *Service) handleObservation(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
+	// Reject requests from internal CLI calls (no session ID = internal callClaudeCLI)
+	if req.ClaudeSessionID == "" {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+
 
 	// Find session
 	sess, err := s.sessionStore.FindAnySDKSession(r.Context(), req.ClaudeSessionID)

internal/worker/handlers_test.go

@@ -459,14 +459,13 @@ func TestHandleHealth_ReturnsVersion(t *testing.T) {
 
 	svc.handleHealth(rec, req)
 
-	assert.Equal(t, http.StatusOK, rec.Code)
-
 	var response map[string]interface{}
 	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
-	assert.Equal(t, "ready", response["status"])
 	assert.Equal(t, "test-version-1.2.3", response["version"])
+	// Status may be "degraded" if embedSvc is nil in test, but version is always present
+	assert.Contains(t, []string{"ready", "degraded"}, response["status"])
 }
 
 func TestHandleVersion(t *testing.T) {
@@ -2028,13 +2027,14 @@ func TestHandleHealth_NotReady(t *testing.T) {
 
 	svc.handleHealth(rec, req)
 
-	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
 
 	var response map[string]interface{}
 	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
-	assert.Equal(t, "starting", response["status"])
+	assert.Equal(t, "initializing", response["status"])
+	assert.Equal(t, false, response["ready"])
 }
 
 // TestHandleContextInject_EmptyProject tests context inject with empty project.
@@ -2399,7 +2399,12 @@ func TestHandleHealthEndpoint(t *testing.T) {
 
 	svc.router.ServeHTTP(rec, req)
 
-	assert.Equal(t, http.StatusOK, rec.Code)
+	// Response is valid JSON with health details
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
+	require.NoError(t, err)
+	assert.NotNil(t, response["status"])
+	assert.NotNil(t, response["version"])
 }
 
 // TestHandleSelfCheckEndpoint tests self-check endpoint via router.
@@ -2894,12 +2899,18 @@ func TestHandleHealth(t *testing.T) {
 
 	svc.router.ServeHTTP(rec, req)
 
-	assert.Equal(t, http.StatusOK, rec.Code)
-
 	var response map[string]interface{}
 	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
-	assert.Equal(t, "ready", response["status"])
+
+	// Test service has store set but no embedSvc, so status is "degraded"
+	assert.Contains(t, []string{"ready", "degraded"}, response["status"])
+	assert.NotNil(t, response["version"])
+	assert.NotNil(t, response["uptime_seconds"])
+	assert.NotNil(t, response["active_sessions"])
+	assert.NotNil(t, response["db_status"])
+	assert.NotNil(t, response["embedding_status"])
+	assert.NotNil(t, response["ready"])
 }
 
 // TestHandleSessionInit_ValidRequest tests session init with valid request.
@@ -3013,3 +3024,42 @@ func TestHandleSessionStart(t *testing.T) {
 	// May return various status codes depending on session state and endpoint
 	assert.Contains(t, []int{http.StatusOK, http.StatusBadRequest, http.StatusNotFound, http.StatusInternalServerError}, rec.Code)
 }
+
+// =============================================================================
+// REGRESSION TESTS FOR handler request-scoped timeouts (Fix #45)
+// =============================================================================
+
+// TestHandleSearchByPrompt_RespectsTimeout verifies that handleSearchByPrompt
+// uses r.Context() as the parent for its internal 15s timeout: if the request
+// context is already cancelled the handler must return quickly rather than
+// hanging for 15 seconds, and must not return StatusOK.
+func TestHandleSearchByPrompt_RespectsTimeout(t *testing.T) {
+	svc, cleanup := testService(t)
+	defer cleanup()
+
+	// Pre-populate a project with an observation so there is DB work to do.
+	createTestObservation(t, svc.observationStore, "timeout-test",
+		"Authentication flow", "JWT token validation", []string{"security"})
+
+	// Build a request with a pre-cancelled context.
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // cancelled before the request is even sent
+
+	req := httptest.NewRequest(http.MethodGet,
+		"/api/context/search?project=timeout-test&query=authentication",
+		nil).WithContext(ctx)
+	rec := httptest.NewRecorder()
+
+	start := time.Now()
+	svc.router.ServeHTTP(rec, req)
+	elapsed := time.Since(start)
+
+	// The handler must not hang for 15 seconds — it inherits the cancelled ctx.
+	assert.Less(t, elapsed, 5*time.Second,
+		"handler should return quickly when request context is already cancelled")
+
+	// A cancelled-context request must not yield a successful 200 response.
+	// Acceptable: any error status, or an empty/error body on 200 (DB returned nothing).
+	// The key regression: it must NOT block for the full 15s timeout.
+	t.Logf("handler returned status=%d in %v", rec.Code, elapsed)
+}

internal/worker/sdk/dedup.go

@@ -0,0 +1,161 @@
+// Package sdk provides write-time observation deduplication via vector similarity.
+package sdk
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/lukaszraczylo/claude-mnemonic/internal/config"
+	"github.com/lukaszraczylo/claude-mnemonic/internal/db/gorm"
+	"github.com/lukaszraczylo/claude-mnemonic/internal/vector/sqlitevec"
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+	"github.com/rs/zerolog/log"
+)
+
+// DeduplicationResult represents the outcome of a vector similarity dedup check.
+type DeduplicationResult struct {
+	ExistingID int64
+	Similarity float64
+	Action     string // "insert", "merge"
+}
+
+// checkVectorDeduplication checks if a similar observation already exists using vector similarity.
+// Returns a result indicating whether to insert or merge, or an error.
+// On any failure, returns Action="insert" so the caller always proceeds with storage.
+func (p *Processor) checkVectorDeduplication(ctx context.Context, obs *models.ParsedObservation, project string) *DeduplicationResult {
+	cfg := config.Get()
+	if !cfg.DeduplicationEnabled {
+		return &DeduplicationResult{Action: "insert"}
+	}
+
+	if p.vectorClient == nil {
+		return &DeduplicationResult{Action: "insert"}
+	}
+
+	// Build search text from observation fields
+	searchText := buildObservationSearchText(obs)
+	if searchText == "" {
+		return &DeduplicationResult{Action: "insert"}
+	}
+
+	// Query vector DB for similar observations in the same project
+	where := sqlitevec.BuildWhereFilter(sqlitevec.DocTypeObservation, project)
+	results, err := p.vectorClient.Query(ctx, searchText, 3, where)
+	if err != nil {
+		log.Debug().Err(err).Msg("Vector search failed during dedup check")
+		return &DeduplicationResult{Action: "insert"}
+	}
+
+	// Check results for high similarity
+	for _, r := range results {
+		if r.Similarity >= cfg.DeduplicationThreshold {
+			obsID := extractObservationIDFromVectorDoc(r)
+			if obsID > 0 {
+				return &DeduplicationResult{
+					ExistingID: obsID,
+					Similarity: r.Similarity,
+					Action:     "merge",
+				}
+			}
+		}
+	}
+
+	return &DeduplicationResult{Action: "insert"}
+}
+
+// buildObservationSearchText creates searchable text from a parsed observation.
+func buildObservationSearchText(obs *models.ParsedObservation) string {
+	var parts []string
+	if obs.Title != "" {
+		parts = append(parts, obs.Title)
+	}
+	if obs.Subtitle != "" {
+		parts = append(parts, obs.Subtitle)
+	}
+	if obs.Narrative != "" {
+		parts = append(parts, obs.Narrative)
+	}
+	text := strings.Join(parts, " ")
+	if len(text) > 2000 {
+		text = text[:2000]
+	}
+	return text
+}
+
+// extractObservationIDFromVectorDoc extracts the SQLite observation ID from a vector query result.
+func extractObservationIDFromVectorDoc(r sqlitevec.QueryResult) int64 {
+	// Prefer the sqlite_id metadata field (set during vector sync)
+	if sqliteID, ok := r.Metadata["sqlite_id"].(float64); ok && sqliteID > 0 {
+		return int64(sqliteID)
+	}
+	if sqliteID, ok := r.Metadata["sqlite_id"].(int64); ok && sqliteID > 0 {
+		return sqliteID
+	}
+
+	// Fallback: parse from doc_id format "obs_{id}_composite" or "obs_{id}_narrative"
+	if !strings.HasPrefix(r.ID, "obs_") {
+		return 0
+	}
+	parts := strings.SplitN(r.ID[4:], "_", 2)
+	if len(parts) == 0 {
+		return 0
+	}
+	var id int64
+	fmt.Sscanf(parts[0], "%d", &id)
+	return id
+}
+
+// mergeObservation updates an existing observation with new information from a duplicate.
+// It appends new facts, updates the narrative if the new one is longer,
+// and bumps the importance score to reflect reconfirmation.
+func (p *Processor) mergeObservation(ctx context.Context, existingID int64, newObs *models.ParsedObservation) error {
+	existing, err := p.observationStore.GetObservationByID(ctx, existingID)
+	if err != nil {
+		return fmt.Errorf("fetch existing observation %d: %w", existingID, err)
+	}
+	if existing == nil {
+		return fmt.Errorf("observation %d not found", existingID)
+	}
+
+	update := &gorm.ObservationUpdate{}
+	changed := false
+
+	// Merge facts: append new facts not already present
+	if len(newObs.Facts) > 0 {
+		existingFactSet := make(map[string]struct{}, len(existing.Facts))
+		for _, f := range existing.Facts {
+			existingFactSet[f] = struct{}{}
+		}
+		mergedFacts := make([]string, len(existing.Facts))
+		copy(mergedFacts, existing.Facts)
+		for _, f := range newObs.Facts {
+			if _, exists := existingFactSet[f]; !exists {
+				mergedFacts = append(mergedFacts, f)
+				changed = true
+			}
+		}
+		if changed {
+			update.Facts = &mergedFacts
+		}
+	}
+
+	// Update narrative if the new one is longer/more detailed
+	if len(newObs.Narrative) > len(existing.Narrative.String) {
+		update.Narrative = &newObs.Narrative
+		changed = true
+	}
+
+	if !changed {
+		// Nothing new to merge, but still count it as a confirmed observation
+		log.Debug().Int64("id", existingID).Msg("Dedup merge: no new content, skipping update")
+		return nil
+	}
+
+	_, err = p.observationStore.UpdateObservation(ctx, existingID, update)
+	if err != nil {
+		return fmt.Errorf("update observation %d: %w", existingID, err)
+	}
+
+	return nil
+}

internal/worker/sdk/dedup_test.go

@@ -0,0 +1,143 @@
+package sdk
+
+import (
+	"testing"
+
+	"github.com/lukaszraczylo/claude-mnemonic/internal/vector/sqlitevec"
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+func TestBuildObservationSearchText(t *testing.T) {
+	tests := []struct {
+		name     string
+		obs      *models.ParsedObservation
+		expected string
+	}{
+		{
+			name:     "empty observation",
+			obs:      &models.ParsedObservation{},
+			expected: "",
+		},
+		{
+			name: "title only",
+			obs: &models.ParsedObservation{
+				Title: "Fix database connection",
+			},
+			expected: "Fix database connection",
+		},
+		{
+			name: "all fields",
+			obs: &models.ParsedObservation{
+				Title:     "Fix database connection",
+				Subtitle:  "Connection pooling issue",
+				Narrative: "The database connection pool was exhausted due to leaked connections.",
+			},
+			expected: "Fix database connection Connection pooling issue The database connection pool was exhausted due to leaked connections.",
+		},
+		{
+			name: "truncates long text",
+			obs: &models.ParsedObservation{
+				Narrative: string(make([]byte, 3000)),
+			},
+			expected: string(make([]byte, 2000)),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := buildObservationSearchText(tt.obs)
+			if result != tt.expected {
+				t.Errorf("got %q, want %q", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestExtractObservationIDFromVectorDoc(t *testing.T) {
+	tests := []struct {
+		name     string
+		result   sqlitevec.QueryResult
+		expected int64
+	}{
+		{
+			name: "from sqlite_id metadata (float64)",
+			result: sqlitevec.QueryResult{
+				ID:       "obs_42_narrative",
+				Metadata: map[string]any{"sqlite_id": float64(42)},
+			},
+			expected: 42,
+		},
+		{
+			name: "from sqlite_id metadata (int64)",
+			result: sqlitevec.QueryResult{
+				ID:       "obs_42_narrative",
+				Metadata: map[string]any{"sqlite_id": int64(42)},
+			},
+			expected: 42,
+		},
+		{
+			name: "fallback to doc_id parsing",
+			result: sqlitevec.QueryResult{
+				ID:       "obs_99_composite",
+				Metadata: map[string]any{},
+			},
+			expected: 99,
+		},
+		{
+			name: "non-observation doc_id",
+			result: sqlitevec.QueryResult{
+				ID:       "summary_5_text",
+				Metadata: map[string]any{},
+			},
+			expected: 0,
+		},
+		{
+			name: "zero sqlite_id falls back to doc_id",
+			result: sqlitevec.QueryResult{
+				ID:       "obs_123_narrative",
+				Metadata: map[string]any{"sqlite_id": float64(0)},
+			},
+			expected: 123,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := extractObservationIDFromVectorDoc(tt.result)
+			if result != tt.expected {
+				t.Errorf("got %d, want %d", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestCheckVectorDeduplication_NilClient(t *testing.T) {
+	p := &Processor{
+		// No vectorClient set
+	}
+
+	obs := &models.ParsedObservation{
+		Title:     "Test observation",
+		Narrative: "Some narrative text",
+	}
+
+	result := p.checkVectorDeduplication(nil, obs, "test-project")
+	if result.Action != "insert" {
+		t.Errorf("expected Action='insert' when vectorClient is nil, got %q", result.Action)
+	}
+}
+
+func TestCheckVectorDeduplication_EmptySearchText(t *testing.T) {
+	p := &Processor{
+		// vectorClient would be set but obs is empty
+	}
+
+	obs := &models.ParsedObservation{
+		// All empty fields
+	}
+
+	result := p.checkVectorDeduplication(nil, obs, "test-project")
+	if result.Action != "insert" {
+		t.Errorf("expected Action='insert' for empty observation, got %q", result.Action)
+	}
+}

internal/worker/sdk/processor.go

@@ -19,6 +19,7 @@ import (
 
 	"github.com/lukaszraczylo/claude-mnemonic/internal/config"
 	"github.com/lukaszraczylo/claude-mnemonic/internal/db/gorm"
+	"github.com/lukaszraczylo/claude-mnemonic/internal/vector/sqlitevec"
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
 	"github.com/lukaszraczylo/claude-mnemonic/pkg/similarity"
 	"github.com/rs/zerolog/log"
@@ -194,6 +195,36 @@ func hashRequest(toolName, input, output string) string {
 	return hex.EncodeToString(h.Sum(nil))[:16]       // Short hash is sufficient
 }
 
+// maxStdoutBytes is the maximum number of bytes to capture from CLI stdout.
+const maxStdoutBytes = 1 * 1024 * 1024 // 1 MiB
+
+// maxStderrBytes is the maximum number of bytes to capture from CLI stderr.
+const maxStderrBytes = 64 * 1024 // 64 KiB
+
+// limitedWriter wraps a bytes.Buffer and silently discards writes beyond a maximum size.
+type limitedWriter struct {
+	buf bytes.Buffer
+	max int
+}
+
+// Write implements io.Writer. It writes up to the remaining capacity and silently discards the rest.
+func (lw *limitedWriter) Write(p []byte) (int, error) {
+	remaining := lw.max - lw.buf.Len()
+	if remaining <= 0 {
+		return len(p), nil // Silently discard
+	}
+	if len(p) > remaining {
+		p = p[:remaining]
+	}
+	lw.buf.Write(p)
+	return len(p), nil
+}
+
+// String returns the buffered content as a string.
+func (lw *limitedWriter) String() string {
+	return lw.buf.String()
+}
+
 // BroadcastFunc is a callback for broadcasting events to SSE clients.
 type BroadcastFunc func(event map[string]any)
 
@@ -212,6 +243,7 @@ const MaxVectorSyncWorkers = 8
 type Processor struct {
 	observationStore    *gorm.ObservationStore
 	summaryStore        *gorm.SummaryStore
+	vectorClient        *sqlitevec.Client
 	broadcastFunc       BroadcastFunc
 	syncObservationFunc SyncObservationFunc
 	syncSummaryFunc     SyncSummaryFunc
@@ -240,6 +272,11 @@ func (p *Processor) SetSyncSummaryFunc(fn SyncSummaryFunc) {
 	p.syncSummaryFunc = fn
 }
 
+// SetVectorClient sets the vector client for write-time deduplication.
+func (p *Processor) SetVectorClient(client *sqlitevec.Client) {
+	p.vectorClient = client
+}
+
 // broadcast sends an event via the broadcast callback if set.
 func (p *Processor) broadcast(event map[string]any) {
 	if p.broadcastFunc != nil {
@@ -429,16 +466,34 @@ func (p *Processor) ProcessObservation(ctx context.Context, sdkSessionID, projec
 		// Convert to stored observation for similarity check
 		storedObs := obs.ToStoredObservation()
 
-		// Check if this observation is too similar to existing ones
+		// Check if this observation is too similar to existing ones (text-based Jaccard)
 		if existingObs != nil && similarity.IsSimilarToAny(storedObs, existingObs, similarityThreshold) {
 			log.Debug().
 				Str("type", string(obs.Type)).
 				Str("title", obs.Title).
-				Msg("Skipping observation - too similar to existing")
+				Msg("Skipping observation - too similar to existing (text)")
 			skippedCount++
 			continue
 		}
 
+		// Check vector similarity for high-confidence dedup with merge
+		dedupResult := p.checkVectorDeduplication(ctx, obs, project)
+		if dedupResult.Action == "merge" {
+			log.Info().
+				Int64("existing_id", dedupResult.ExistingID).
+				Float64("similarity", dedupResult.Similarity).
+				Str("title", obs.Title).
+				Msg("Merging duplicate observation (vector dedup)")
+			if err := p.mergeObservation(ctx, dedupResult.ExistingID, obs); err != nil {
+				log.Warn().Err(err).Int64("existing_id", dedupResult.ExistingID).
+					Msg("Merge failed, inserting as new observation")
+				// Fall through to normal insert
+			} else {
+				skippedCount++
+				continue
+			}
+		}
+
 		id, createdAtEpoch, err := p.observationStore.StoreObservation(ctx, sdkSessionID, project, obs, promptNumber, 0)
 		if err != nil {
 			log.Error().Err(err).Msg("Failed to store observation")
@@ -641,13 +696,19 @@ func (p *Processor) callClaudeCLI(ctx context.Context, prompt string) (string, e
 	// (hooks are triggered based on working directory)
 	cmd.Dir = "/tmp"
 
-	// Disable any plugin hooks by setting an env var that our hooks can check
+	// Disable any plugin hooks by setting an env var that our hooks can check.
+	// NOTE: This env var is NOT reliably propagated to hook subprocesses because
+	// Claude Code constructs its own environment for hooks. The server-side check
+	// in handleSessionInit (handlers_sessions.go) provides the reliable guard by
+	// detecting the system prompt signature in the prompt text. This env var is
+	// kept as a best-effort defense-in-depth measure for cases where it does work.
 	cmd.Env = append(os.Environ(), "CLAUDE_MNEMONIC_INTERNAL=1")
 
-	// Capture output
-	var stdout, stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
+	// Capture output with size limits to prevent unbounded memory usage
+	stdout := &limitedWriter{max: maxStdoutBytes}
+	stderr := &limitedWriter{max: maxStderrBytes}
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr
 
 	// Run command
 	err := cmd.Run()

internal/worker/sdk/prompts.go

@@ -49,6 +49,10 @@ func BuildObservationPrompt(exec ToolExecution) string {
 	inputJSON, _ := json.MarshalIndent(toolInput, "  ", "  ")
 	outputJSON, _ := json.MarshalIndent(toolOutput, "  ", "  ")
 
+	// Strip system XML artifacts from tool data before building prompt
+	cleanInput := StripSystemXML(string(inputJSON))
+	cleanOutput := StripSystemXML(string(outputJSON))
+
 	timestamp := time.UnixMilli(exec.CreatedAtEpoch).Format(time.RFC3339)
 
 	var sb strings.Builder
@@ -58,8 +62,8 @@ func BuildObservationPrompt(exec ToolExecution) string {
 	if exec.CWD != "" {
 		sb.WriteString(fmt.Sprintf("  <working_directory>%s</working_directory>\n", exec.CWD))
 	}
-	sb.WriteString(fmt.Sprintf("  <parameters>%s</parameters>\n", truncate(string(inputJSON), 3000)))
-	sb.WriteString(fmt.Sprintf("  <outcome>%s</outcome>\n", truncate(string(outputJSON), 5000)))
+	sb.WriteString(fmt.Sprintf("  <parameters>%s</parameters>\n", truncate(cleanInput, 3000)))
+	sb.WriteString(fmt.Sprintf("  <outcome>%s</outcome>\n", truncate(cleanOutput, 5000)))
 	sb.WriteString("</observed_from_primary_session>")
 
 	return sb.String()
@@ -84,8 +88,10 @@ func BuildSummaryPrompt(req SummaryRequest) string {
 	sb.WriteString("Write progress notes of what was done, what was learned, and what's next. This is a checkpoint to capture progress so far. The session is ongoing - you may receive more requests and tool executions after this summary. Write \"next_steps\" as the current trajectory of work (what's actively being worked on or coming up next), not as post-session future work. Always write at least a minimal summary explaining current progress, even if work is still in early stages, so that users see a summary output tied to each request.\n\n")
 
 	if req.LastAssistantMessage != "" {
+		// Strip system XML artifacts from captured transcript content
+		cleanMsg := StripSystemXML(req.LastAssistantMessage)
 		sb.WriteString("Claude's Full Response to User:\n")
-		sb.WriteString(truncate(req.LastAssistantMessage, 4000))
+		sb.WriteString(truncate(cleanMsg, 4000))
 		sb.WriteString("\n\n")
 	}
 

internal/worker/sdk/sanitize.go

@@ -0,0 +1,8 @@
+// Package sdk provides SDK agent integration for claude-mnemonic.
+package sdk
+
+import "github.com/lukaszraczylo/claude-mnemonic/pkg/sanitize"
+
+// StripSystemXML removes known Claude Code internal XML blocks from text.
+// Delegates to the shared sanitize package.
+var StripSystemXML = sanitize.StripSystemXML

internal/worker/service.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"sync"
 	"sync/atomic"
+	"syscall"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -43,6 +44,13 @@ const (
 	// QueueProcessInterval is how often the background queue processor runs.
 	QueueProcessInterval = 2 * time.Second
 
+	// reinitializationDrainDelay is the delay after marking the service as not ready
+	// to allow in-flight requests to complete before reinitializing.
+	reinitializationDrainDelay = 200 * time.Millisecond
+
+	// MaxConcurrentProcessing limits the number of concurrent session processing goroutines.
+	MaxConcurrentProcessing = 4
+
 	// VectorSyncMaxRetries is the maximum number of retries for vector sync operations.
 	VectorSyncMaxRetries = 3
 
@@ -138,6 +146,7 @@ type Service struct {
 	updater            *update.Updater
 	rateLimiter        *PerClientRateLimiter
 	expensiveOpLimiter *ExpensiveOperationLimiter
+	contextCache       sync.Map
 	version            string
 	recentQueriesBuf   [maxRecentQueries]RecentSearchQuery
 	wg                 sync.WaitGroup
@@ -178,6 +187,13 @@ type staleVerifyRequest struct {
 	observationID int64
 }
 
+// contextCacheEntry caches clustering results for context injection.
+type contextCacheEntry struct {
+	timestamp    time.Time
+	observations []*models.Observation
+	obsCount     int
+}
+
 // RecentSearchQuery tracks a search query for analytics.
 type RecentSearchQuery struct {
 	Timestamp  time.Time `json:"timestamp"`
@@ -288,6 +304,11 @@ func (s *Service) setupVectorSyncCallbacks(
 		})
 	}
 
+	// Set vector client on processor for write-time deduplication
+	if processor != nil && s.vectorClient != nil {
+		processor.SetVectorClient(s.vectorClient)
+	}
+
 	// Set cleanup callback on observation store to sync deletes to vector store
 	if observationStore != nil && vectorSync != nil {
 		observationStore.SetCleanupFunc(func(ctx context.Context, deletedIDs []int64) {
@@ -346,9 +367,9 @@ func NewService(version string) (*Service, error) {
 	router := chi.NewRouter()
 	sseBroadcaster := sse.NewBroadcaster()
 
-	// Determine install directory (plugin location)
+	// Determine install directory (stable binary location, survives Claude Code updates)
 	homeDir, _ := os.UserHomeDir()
-	installDir := fmt.Sprintf("%s/.claude/plugins/marketplaces/claude-mnemonic", homeDir)
+	installDir := fmt.Sprintf("%s/.claude-mnemonic/bin", homeDir)
 
 	// Create rate limiter with generous limits (100 req/sec, burst of 200)
 	// These limits are per-client and allow for intensive CLI usage
@@ -614,6 +635,7 @@ func (s *Service) startWatchers() {
 func (s *Service) reinitializeDatabase() {
 	// Block new requests
 	s.ready.Store(false)
+	time.Sleep(reinitializationDrainDelay) // Allow in-flight requests to complete
 	log.Info().Msg("Database reinitialization starting...")
 
 	// Get old store references
@@ -715,10 +737,14 @@ func (s *Service) reinitializeDatabase() {
 		log.Info().Msg("Query expansion reconnected after reinit")
 	}
 
-	// Close old reranker if exists
+	// Close old vector client and reranker before swapping
 	s.initMu.RLock()
+	oldVectorClient := s.vectorClient
 	oldReranker := s.reranker
 	s.initMu.RUnlock()
+	if oldVectorClient != nil {
+		_ = oldVectorClient.Close()
+	}
 	if oldReranker != nil {
 		_ = oldReranker.Close()
 	}
@@ -794,8 +820,11 @@ func (s *Service) reloadConfig() {
 	// Give SSE clients a moment to receive the message
 	time.Sleep(100 * time.Millisecond)
 
-	// Exit cleanly - hooks will restart us with new config
-	os.Exit(0)
+	// Send SIGTERM to self for graceful shutdown (hooks will restart us)
+	p, err := os.FindProcess(os.Getpid())
+	if err == nil {
+		_ = p.Signal(syscall.SIGTERM)
+	}
 }
 
 // setInitError records an initialization error.
@@ -1217,7 +1246,12 @@ func (s *Service) setupRoutes() {
 	s.router.Get("/api/selfcheck", s.handleSelfCheck)
 
 	// SSE endpoint (works before DB is ready)
-	s.router.Get("/api/events", s.sseBroadcaster.HandleSSE)
+	// Wrap with middleware that disables write deadline since SSE connections are long-lived
+	s.router.Get("/api/events", func(w http.ResponseWriter, r *http.Request) {
+		rc := http.NewResponseController(w)
+		_ = rc.SetWriteDeadline(time.Time{}) // no deadline for SSE
+		s.sseBroadcaster.HandleSSE(w, r)
+	})
 
 	// Routes that require DB to be ready
 	s.router.Group(func(r chi.Router) {
@@ -1517,7 +1551,7 @@ func (s *Service) Start() error {
 		Handler:           s.router,
 		ReadHeaderTimeout: 10 * time.Second,
 		ReadTimeout:       30 * time.Second,
-		WriteTimeout:      0, // Disabled for SSE (long-lived connections)
+		WriteTimeout:      60 * time.Second, // Default for API routes; SSE handler extends per-request
 		IdleTimeout:       120 * time.Second,
 	}
 
@@ -1571,15 +1605,17 @@ func (s *Service) processQueue() {
 	ticker := time.NewTicker(QueueProcessInterval)
 	defer ticker.Stop()
 
+	s.initMu.RLock()
+	notify := s.sessionManager.ProcessNotify
+	s.initMu.RUnlock()
+
 	for {
 		select {
 		case <-s.ctx.Done():
 			return
-		case <-s.sessionManager.ProcessNotify:
-			// Immediate processing when observation is queued
+		case <-notify:
 			s.processAllSessions()
 		case <-ticker.C:
-			// Fallback periodic processing
 			s.processAllSessions()
 		}
 	}
@@ -1587,31 +1623,43 @@ func (s *Service) processQueue() {
 
 // processAllSessions processes pending messages for all active sessions.
 // Messages are processed in parallel using goroutines, with concurrency
-// limited by the processor's semaphore.
+// limited by a channel-based semaphore.
 func (s *Service) processAllSessions() {
-	// Get all sessions with pending messages
-	sessions := s.sessionManager.GetAllSessions()
+	s.initMu.RLock()
+	mgr := s.sessionManager
+	proc := s.processor
+	s.initMu.RUnlock()
+	if mgr == nil || proc == nil {
+		return
+	}
+
+	sessions := mgr.GetAllSessions()
 
 	var wg sync.WaitGroup
+	sem := make(chan struct{}, MaxConcurrentProcessing)
 
 	for _, sess := range sessions {
-		// Get pending messages
-		messages := s.sessionManager.DrainMessages(sess.SessionDBID)
+		messages := mgr.DrainMessages(sess.SessionDBID)
 		if len(messages) == 0 {
 			continue
 		}
 
-		// Process each message in a goroutine
 		for _, msg := range messages {
 			wg.Add(1)
+			sem <- struct{}{}
 			go func(sess *session.ActiveSession, msg session.PendingMessage) {
 				defer wg.Done()
+				defer func() { <-sem }()
+
+				// Timeout prevents a hung subprocess from blocking the queue processor forever
+				procCtx, procCancel := context.WithTimeout(s.ctx, 60*time.Second)
+				defer procCancel()
 
 				switch msg.Type {
 				case session.MessageTypeObservation:
 					if msg.Observation != nil {
-						err := s.processor.ProcessObservation(
-							s.ctx,
+						err := proc.ProcessObservation(
+							procCtx,
 							sess.SDKSessionID,
 							sess.Project,
 							msg.Observation.ToolName,
@@ -1629,8 +1677,8 @@ func (s *Service) processAllSessions() {
 
 				case session.MessageTypeSummarize:
 					if msg.Summarize != nil {
-						err := s.processor.ProcessSummary(
-							s.ctx,
+						err := proc.ProcessSummary(
+							procCtx,
 							sess.SessionDBID,
 							sess.SDKSessionID,
 							sess.Project,
@@ -1643,18 +1691,15 @@ func (s *Service) processAllSessions() {
 								Int64("sessionId", sess.SessionDBID).
 								Msg("Failed to process summary")
 						}
-						// Delete session after summary
-						s.sessionManager.DeleteSession(sess.SessionDBID)
+						mgr.DeleteSession(sess.SessionDBID)
 					}
 				}
 			}(sess, msg)
 		}
 	}
 
-	// Wait for all goroutines to complete
 	wg.Wait()
 
-	// Broadcast status after processing
 	s.broadcastProcessingStatus()
 }
 
@@ -1763,8 +1808,15 @@ func (s *Service) Shutdown(ctx context.Context) error {
 
 // broadcastProcessingStatus broadcasts the current processing status.
 func (s *Service) broadcastProcessingStatus() {
-	isProcessing := s.sessionManager.IsAnySessionProcessing()
-	queueDepth := s.sessionManager.GetTotalQueueDepth()
+	s.initMu.RLock()
+	mgr := s.sessionManager
+	s.initMu.RUnlock()
+	if mgr == nil {
+		return
+	}
+
+	isProcessing := mgr.IsAnySessionProcessing()
+	queueDepth := mgr.GetTotalQueueDepth()
 
 	s.sseBroadcaster.Broadcast(map[string]any{
 		"type":         "processing_status",

internal/worker/session/manager.go

@@ -75,6 +75,7 @@ type Manager struct {
 	onDeleted     func(int64)
 	cancel        context.CancelFunc
 	ProcessNotify chan struct{}
+	wg            sync.WaitGroup
 	mu            sync.RWMutex
 }
 
@@ -89,12 +90,14 @@ func NewManager(sessionStore *gorm.SessionStore) *Manager {
 		ProcessNotify: make(chan struct{}, 1),
 	}
 	// Start background cleanup goroutine
+	m.wg.Add(1)
 	go m.cleanupLoop()
 	return m
 }
 
 // cleanupLoop periodically removes stale sessions.
 func (m *Manager) cleanupLoop() {
+	defer m.wg.Done()
 	ticker := time.NewTicker(CleanupInterval)
 	defer ticker.Stop()
 
@@ -350,6 +353,7 @@ func (m *Manager) DeleteSession(sessionDBID int64) {
 func (m *Manager) ShutdownAll(ctx context.Context) {
 	// Stop cleanup goroutine
 	m.cancel()
+	m.wg.Wait()
 
 	m.mu.Lock()
 	sessionIDs := make([]int64, 0, len(m.sessions))

internal/worker/session/manager_test.go

@@ -952,6 +952,7 @@ func TestCleanupLoop_ExitsOnCancel(t *testing.T) {
 
 	// Start cleanup loop in goroutine
 	done := make(chan struct{})
+	manager.wg.Add(1)
 	go func() {
 		manager.cleanupLoop()
 		close(done)

internal/worker/sse/broadcaster.go

@@ -212,7 +212,7 @@ func (b *Broadcaster) HandleSSE(w http.ResponseWriter, r *http.Request) {
 	defer b.RemoveClient(client)
 
 	// Send initial connection message
-	fmt.Fprintf(w, "data: {\"type\":\"connected\",\"clientId\":\"%s\"}\n\n", client.ID)
+	_, _ = fmt.Fprintf(w, "data: {\"type\":\"connected\",\"clientId\":\"%s\"}\n\n", client.ID)
 	client.Flusher.Flush()
 
 	// Wait for client disconnect

marketplace.json

@@ -13,7 +13,7 @@
     {
       "name": "claude-mnemonic",
       "description": "Persistent memory system for Claude Code - Go implementation with SQLite and ChromaDB vector search",
-      "version": "0.11.17",
+      "version": "0.12.21",
       "author": {
         "name": "lukaszraczylo",
         "url": "https://github.com/lukaszraczylo"
@@ -23,25 +23,25 @@
       "license": "MIT",
       "homepage": "https://github.com/lukaszraczylo/claude-mnemonic",
       "releases": {
-        "latest": "0.11.17",
+        "latest": "0.12.21",
         "versions": {
-          "0.11.17": {
-            "releaseDate": "2026-01-11",
+          "0.12.21": {
+            "releaseDate": "2026-05-26",
             "downloads": {
               "darwin-arm64": {
-                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.11.17/claude-mnemonic_0.11.17_darwin_arm64.tar.gz",
+                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.12.21/claude-mnemonic_0.12.21_darwin_arm64.tar.gz",
                 "format": "tar.gz",
-                "sha256": "dbc5f314635332b7196e1d8c6153a1d825b1b4258dc37b109682a536d6a30341"
+                "sha256": "3f4709de5fe129c1e6ad3fa4bc9347b650e06539ef89f10b77105ff1bc661dee"
               },
               "linux-amd64": {
-                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.11.17/claude-mnemonic_0.11.17_linux_amd64.tar.gz",
+                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.12.21/claude-mnemonic_0.12.21_linux_amd64.tar.gz",
                 "format": "tar.gz",
-                "sha256": "5b61a8096541a374c3daf8ecaf36bcb41daea06f070998936bd1251bffb4ac55"
+                "sha256": "0f761ec3eb6d34e51514d4f8f1ea6a62c1b7103ade23ce5ad057143515b8cc91"
               },
               "windows-amd64": {
-                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.11.17/claude-mnemonic_0.11.17_windows_amd64.zip",
+                "url": "https://github.com/lukaszraczylo/claude-mnemonic/releases/download/v0.12.21/claude-mnemonic_0.12.21_windows_amd64.zip",
                 "format": "zip",
-                "sha256": "063ea339de75760a7798eab963eb960f49ab5a909ca05076e1814e0cbded1f68"
+                "sha256": "34666da29446467bed14b3c6ab92e417bd1db9c8610bfea4edfe5325f69da690"
               }
             }
           }

mcp-server

@@ -0,0 +1,6 @@
+#!/bin/sh
+BIN="$HOME/.claude-mnemonic/bin/mcp-server"
+[ -x "$BIN" ] && exec "$BIN" "$@"
+echo "claude-mnemonic: mcp-server not found at $BIN" >&2
+echo "Install: cd $(dirname "$0") && make install" >&2
+exit 1

pkg/hooks/procattr_unix.go

@@ -0,0 +1,12 @@
+//go:build !windows
+
+package hooks
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+func setSysProcAttr(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+}

pkg/hooks/procattr_windows.go

@@ -0,0 +1,9 @@
+//go:build windows
+
+package hooks
+
+import "os/exec"
+
+func setSysProcAttr(cmd *exec.Cmd) {
+	// Windows has no Setpgid; process groups work differently.
+}

pkg/hooks/response.go

@@ -2,6 +2,7 @@
 package hooks
 
 import (
+	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
@@ -9,6 +10,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"time"
 )
 
 // HookResponse is the response sent back to Claude Code.
@@ -31,6 +33,14 @@ func ProjectIDWithName(cwd string) string {
 	return fmt.Sprintf("%s_%s", dirName, shortHash)
 }
 
+// HookDeadline returns a context with the hook's timeout budget minus a safety margin.
+// This ensures hooks return gracefully before Claude kills them.
+func HookDeadline(timeout time.Duration) (context.Context, context.CancelFunc) {
+	// Use 80% of the timeout to leave margin for response serialization
+	safeTimeout := time.Duration(float64(timeout) * 0.8)
+	return context.WithTimeout(context.Background(), safeTimeout)
+}
+
 // Exit codes for Claude Code hooks
 const (
 	ExitSuccess         = 0
@@ -92,7 +102,7 @@ func RunHook[T any](hookName string, handler HookHandler[T]) {
 
 	// Parse input
 	var input T
-	if err := json.Unmarshal(inputData, &input); err != nil {
+	if err = json.Unmarshal(inputData, &input); err != nil {
 		WriteError(hookName, err)
 		os.Exit(1)
 	}

pkg/hooks/worker.go

@@ -3,6 +3,7 @@ package hooks
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"net"
@@ -12,6 +13,8 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
+	"syscall"
 	"time"
 )
 
@@ -22,13 +25,77 @@ const (
 	// DefaultWorkerPort is the default worker port.
 	DefaultWorkerPort = 37777
 
-	// HealthCheckTimeout is the timeout for health checks (reduced from 5s for faster startup).
-	HealthCheckTimeout = 1 * time.Second
+	// HealthCheckTimeout is the timeout for health checks.
+	HealthCheckTimeout = 2 * time.Second
 
 	// StartupTimeout is the timeout for worker startup.
-	StartupTimeout = 30 * time.Second
+	StartupTimeout = 10 * time.Second
+
+	// EnsureWorkerDeadline is the hard overall deadline for EnsureWorkerRunning.
+	// Must fit within Claude Code's hook timeout budget.
+	EnsureWorkerDeadline = 15 * time.Second
+
+	// workerCacheMaxAge is how long the worker cache is considered fresh.
+	workerCacheMaxAge = 10 * time.Second
+
+	// circuitBreakerCooldown is how long to wait after a startup failure before retrying.
+	circuitBreakerCooldown = 30 * time.Second
+
+	// healthCheckRetries is the number of health check attempts before declaring dead.
+	healthCheckRetries = 3
+
+	// healthCheckRetryDelay is the delay between health check retries.
+	healthCheckRetryDelay = 200 * time.Millisecond
 )
 
+var (
+	// circuitBreakerMu protects lastStartupFailure.
+	circuitBreakerMu   sync.Mutex
+	lastStartupFailure time.Time
+
+	// hookClient is a shared HTTP client for hook->worker requests.
+	// DisableKeepAlives prevents TIME_WAIT connection leaks since each hook
+	// is a separate OS process that exits quickly.
+	hookClient = &http.Client{
+		Timeout: 10 * time.Second,
+		Transport: &http.Transport{
+			DisableKeepAlives: true,
+			MaxIdleConns:      1,
+		},
+	}
+
+	// healthClient is a shared HTTP client for health/version checks.
+	healthClient = &http.Client{
+		Timeout: HealthCheckTimeout,
+		Transport: &http.Transport{
+			DisableKeepAlives: true,
+			MaxIdleConns:      1,
+		},
+	}
+)
+
+// IsWorkerAvailable performs a fast check without network calls.
+// Returns true if the worker is likely available, false if definitely down.
+func IsWorkerAvailable() bool {
+	// Check circuit breaker first
+	circuitBreakerMu.Lock()
+	if !lastStartupFailure.IsZero() && time.Since(lastStartupFailure) < circuitBreakerCooldown {
+		circuitBreakerMu.Unlock()
+		return false
+	}
+	circuitBreakerMu.Unlock()
+
+	// Check PID cache
+	entry := readWorkerCache()
+	if entry == nil {
+		return true // No cache = unknown, don't block
+	}
+
+	// Cache exists and is fresh (readWorkerCache already checks staleness)
+	// Check if cached process is alive
+	return isProcessAlive(entry.PID)
+}
+
 // GetWorkerPort returns the worker port from environment or default.
 func GetWorkerPort() int {
 	if port := os.Getenv("CLAUDE_MNEMONIC_WORKER_PORT"); port != "" {
@@ -40,56 +107,222 @@ func GetWorkerPort() int {
 }
 
 // IsWorkerRunning checks if the worker is running and healthy.
+// Parses the JSON health response to check the "ready" field when available.
+// Falls back to HTTP status code check for backwards compatibility.
 func IsWorkerRunning(port int) bool {
-	client := &http.Client{Timeout: HealthCheckTimeout}
-	resp, err := client.Get(fmt.Sprintf("http://127.0.0.1:%d/api/health", port))
+	resp, err := healthClient.Get(fmt.Sprintf("http://127.0.0.1:%d/api/health", port))
 	if err != nil {
 		return false
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
+
+	// Try to parse JSON response for structured health check
+	var health struct {
+		Ready bool `json:"ready"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&health); err == nil {
+		return health.Ready
+	}
+
+	// Fallback: treat HTTP 200 as healthy (backwards compatibility)
 	return resp.StatusCode == http.StatusOK
 }
 
+// workerCachePath returns the path to the worker cache file.
+func workerCachePath() string {
+	home := os.Getenv("HOME")
+	if home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".claude-mnemonic", ".worker-cache")
+}
+
+// workerCacheEntry holds cached worker state: "port:pid:timestamp".
+type workerCacheEntry struct {
+	Timestamp time.Time
+	Port      int
+	PID       int
+}
+
+// readWorkerCache reads the worker cache file and returns the entry if fresh.
+func readWorkerCache() *workerCacheEntry {
+	path := workerCachePath()
+	if path == "" {
+		return nil
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	parts := strings.SplitN(strings.TrimSpace(string(data)), ":", 3)
+	if len(parts) != 3 {
+		return nil
+	}
+	port, err := strconv.Atoi(parts[0])
+	if err != nil || port <= 0 {
+		return nil
+	}
+	pid, err := strconv.Atoi(parts[1])
+	if err != nil || pid <= 0 {
+		return nil
+	}
+	ts, err := strconv.ParseInt(parts[2], 10, 64)
+	if err != nil {
+		return nil
+	}
+	entry := &workerCacheEntry{
+		Port:      port,
+		PID:       pid,
+		Timestamp: time.Unix(ts, 0),
+	}
+	// Check freshness
+	if time.Since(entry.Timestamp) > workerCacheMaxAge {
+		return nil
+	}
+	return entry
+}
+
+// writeWorkerCache writes the worker cache file.
+func writeWorkerCache(port, pid int) {
+	path := workerCachePath()
+	if path == "" {
+		return
+	}
+	// Ensure directory exists
+	dir := filepath.Dir(path)
+	_ = os.MkdirAll(dir, 0o700)
+	data := fmt.Sprintf("%d:%d:%d", port, pid, time.Now().Unix())
+	_ = os.WriteFile(path, []byte(data), 0o600)
+}
+
+// isProcessAlive checks if a process with the given PID exists and is alive.
+func isProcessAlive(pid int) bool {
+	proc, err := os.FindProcess(pid)
+	if err != nil {
+		return false
+	}
+	// Signal 0 checks if process exists without actually sending a signal.
+	err = proc.Signal(syscall.Signal(0))
+	return err == nil
+}
+
+// isWorkerRunningWithRetries checks if the worker is running, retrying on timeout.
+// Returns true only if health check succeeds. Returns false if all retries fail.
+func isWorkerRunningWithRetries(port int) bool {
+	for i := 0; i < healthCheckRetries; i++ {
+		if IsWorkerRunning(port) {
+			return true
+		}
+		if i < healthCheckRetries-1 {
+			time.Sleep(healthCheckRetryDelay)
+		}
+	}
+	return false
+}
+
 // EnsureWorkerRunning ensures the worker is running, starting it if necessary.
 // If a worker is already running and healthy with matching version, it reuses it.
 // If version mismatch or unhealthy, it kills the old worker and starts fresh.
+// A hard deadline of EnsureWorkerDeadline prevents exceeding Claude Code's hook timeout.
 func EnsureWorkerRunning() (int, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), EnsureWorkerDeadline)
+	defer cancel()
+
+	return ensureWorkerRunningCtx(ctx)
+}
+
+// sleepCtx sleeps for d or returns early if ctx is cancelled.
+func sleepCtx(ctx context.Context, d time.Duration) error {
+	select {
+	case <-time.After(d):
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func ensureWorkerRunningCtx(ctx context.Context) (int, error) {
 	port := GetWorkerPort()
 
-	// Check if already running and healthy
-	if IsWorkerRunning(port) {
+	// Fast path: check PID cache before making any HTTP calls.
+	if entry := readWorkerCache(); entry != nil && entry.Port == port {
+		if isProcessAlive(entry.PID) {
+			return port, nil
+		}
+	}
+
+	if ctx.Err() != nil {
+		return 0, ctx.Err()
+	}
+
+	// Circuit breaker: if we failed to start recently, don't retry immediately.
+	circuitBreakerMu.Lock()
+	if !lastStartupFailure.IsZero() && time.Since(lastStartupFailure) < circuitBreakerCooldown {
+		circuitBreakerMu.Unlock()
+		return 0, fmt.Errorf("worker startup failed recently (circuit breaker open, retry after %v)", circuitBreakerCooldown-time.Since(lastStartupFailure))
+	}
+	circuitBreakerMu.Unlock()
+
+	// Check if already running and healthy (with retries to avoid false negatives under load)
+	if isWorkerRunningWithRetries(port) {
 		// Check version - if mismatch, restart (unless both are dev builds)
 		if runningVersion := GetWorkerVersion(port); runningVersion != "" {
 			if runningVersion != Version {
 				// For dev/dirty builds, don't restart if base versions match
 				if versionsCompatible(runningVersion, Version) {
+					updateCacheFromPort(port)
 					return port, nil
 				}
 				fmt.Fprintf(os.Stderr, "[claude-mnemonic] Worker version mismatch (running: %s, expected: %s), restarting...\n", runningVersion, Version)
 				if err := KillProcessOnPort(port); err != nil {
 					fmt.Fprintf(os.Stderr, "[claude-mnemonic] Warning: failed to kill old worker: %v\n", err)
 				}
-				time.Sleep(500 * time.Millisecond)
+				if err := sleepCtx(ctx, 500*time.Millisecond); err != nil {
+					return 0, err
+				}
 			} else {
 				// Version matches, reuse existing worker
+				updateCacheFromPort(port)
 				return port, nil
 			}
 		} else {
 			// Couldn't get version, assume it's fine
+			updateCacheFromPort(port)
 			return port, nil
 		}
 	}
 
-	// Check if port is in use but worker is unhealthy
+	if ctx.Err() != nil {
+		return 0, ctx.Err()
+	}
+
+	// Port is in use but health check failed -- worker may be slow, not dead.
 	if IsPortInUse(port) {
-		// Something is using the port but not responding to health checks
-		// Try to kill it
+		// The port is responding to TCP but health check timed out.
+		// Don't kill it -- it's likely just under load. Give it more time.
+		fmt.Fprintf(os.Stderr, "[claude-mnemonic] Worker on port %d is slow to respond, waiting...\n", port)
+		// Try a couple more times with shorter delays before giving up
+		for i := 0; i < 2; i++ {
+			if err := sleepCtx(ctx, 300*time.Millisecond); err != nil {
+				return 0, err
+			}
+			if IsWorkerRunning(port) {
+				updateCacheFromPort(port)
+				return port, nil
+			}
+		}
+		// Still not healthy after extended wait -- kill and restart
+		fmt.Fprintf(os.Stderr, "[claude-mnemonic] Worker unresponsive after extended wait, restarting...\n")
 		if err := KillProcessOnPort(port); err != nil {
-			// Log but continue - maybe it will die on its own
 			fmt.Fprintf(os.Stderr, "[claude-mnemonic] Warning: failed to kill unhealthy process on port %d: %v\n", port, err)
 		}
-		// Wait a moment for port to be released
-		time.Sleep(500 * time.Millisecond)
+		if err := sleepCtx(ctx, 500*time.Millisecond); err != nil {
+			return 0, err
+		}
+	}
+
+	if ctx.Err() != nil {
+		return 0, ctx.Err()
 	}
 
 	// Find worker binary
@@ -98,42 +331,76 @@ func EnsureWorkerRunning() (int, error) {
 		return 0, fmt.Errorf("worker binary not found")
 	}
 
-	// Start worker
+	// Start worker -- detach from hook's process group so Claude Code
+	// killing the hook doesn't take the worker down with it.
 	cmd := exec.Command(workerPath) // #nosec G204 -- workerPath is from internal findWorkerBinary
+	setSysProcAttr(cmd)
 	cmd.Stdout = os.Stderr
 	cmd.Stderr = os.Stderr
 	if err := cmd.Start(); err != nil {
+		circuitBreakerMu.Lock()
+		lastStartupFailure = time.Now()
+		circuitBreakerMu.Unlock()
 		return 0, fmt.Errorf("failed to start worker: %w", err)
 	}
 
+	pid := cmd.Process.Pid
+
 	// Wait for worker to be ready with exponential backoff
-	deadline := time.Now().Add(StartupTimeout)
 	backoff := 50 * time.Millisecond
 	maxBackoff := 500 * time.Millisecond
 
-	for time.Now().Before(deadline) {
+	for {
+		if ctx.Err() != nil {
+			circuitBreakerMu.Lock()
+			lastStartupFailure = time.Now()
+			circuitBreakerMu.Unlock()
+			return 0, fmt.Errorf("worker failed to start within deadline: %w", ctx.Err())
+		}
 		if IsWorkerRunning(port) {
+			writeWorkerCache(port, pid)
 			return port, nil
 		}
-		time.Sleep(backoff)
+		if err := sleepCtx(ctx, backoff); err != nil {
+			circuitBreakerMu.Lock()
+			lastStartupFailure = time.Now()
+			circuitBreakerMu.Unlock()
+			return 0, fmt.Errorf("worker failed to start within deadline: %w", err)
+		}
 		// Exponential backoff with cap
 		backoff = backoff * 2
 		if backoff > maxBackoff {
 			backoff = maxBackoff
 		}
 	}
+}
 
-	return 0, fmt.Errorf("worker failed to start within timeout")
+// updateCacheFromPort finds the PID of the process on the port and updates the cache.
+func updateCacheFromPort(port int) {
+	cmd := exec.Command("lsof", "-t", "-i", fmt.Sprintf(":%d", port)) // #nosec G204 -- port is from internal config
+	output, err := cmd.Output()
+	if err != nil {
+		return
+	}
+	pidStr := strings.TrimSpace(string(output))
+	// Take first PID if multiple
+	if idx := strings.Index(pidStr, "\n"); idx > 0 {
+		pidStr = pidStr[:idx]
+	}
+	pid, err := strconv.Atoi(pidStr)
+	if err != nil || pid <= 0 {
+		return
+	}
+	writeWorkerCache(port, pid)
 }
 
 // GetWorkerVersion gets the version of the running worker.
 func GetWorkerVersion(port int) string {
-	client := &http.Client{Timeout: HealthCheckTimeout}
-	resp, err := client.Get(fmt.Sprintf("http://127.0.0.1:%d/api/version", port))
+	resp, err := healthClient.Get(fmt.Sprintf("http://127.0.0.1:%d/api/version", port))
 	if err != nil {
 		return ""
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
 		return ""
@@ -195,7 +462,15 @@ func KillProcessOnPort(port int) error {
 
 // findWorkerBinary finds the worker binary path.
 func findWorkerBinary() string {
-	// Check CLAUDE_PLUGIN_ROOT first (set by Claude Code when running hooks)
+	home := os.Getenv("HOME")
+
+	// Stable binary location (primary, survives Claude Code updates)
+	stablePath := filepath.Join(home, ".claude-mnemonic", "bin", "worker")
+	if _, err := os.Stat(stablePath); err == nil {
+		return stablePath
+	}
+
+	// Check CLAUDE_PLUGIN_ROOT (set by Claude Code when running hooks)
 	if pluginRoot := os.Getenv("CLAUDE_PLUGIN_ROOT"); pluginRoot != "" {
 		workerPath := filepath.Join(pluginRoot, "worker")
 		if _, err := os.Stat(workerPath); err == nil {
@@ -204,12 +479,9 @@ func findWorkerBinary() string {
 	}
 
 	// Check common locations
-	home := os.Getenv("HOME")
 	locations := []string{
 		"./worker",
 		"./bin/worker",
-		filepath.Join(home, ".claude/plugins/cache/claude-mnemonic/claude-mnemonic/1.0.0/worker"),
-		filepath.Join(home, ".claude/plugins/marketplaces/claude-mnemonic/worker"),
 	}
 
 	for _, loc := range locations {
@@ -218,6 +490,18 @@ func findWorkerBinary() string {
 		}
 	}
 
+	// Try cache directory with any version
+	matches, _ := filepath.Glob(filepath.Join(home, ".claude/plugins/cache/claude-mnemonic/claude-mnemonic/*/worker"))
+	if len(matches) > 0 {
+		return matches[len(matches)-1]
+	}
+
+	// Try marketplaces directory
+	marketplacePath := filepath.Join(home, ".claude/plugins/marketplaces/claude-mnemonic/worker")
+	if _, err := os.Stat(marketplacePath); err == nil {
+		return marketplacePath
+	}
+
 	// Try PATH
 	if path, err := exec.LookPath("claude-mnemonic-worker"); err == nil {
 		return path
@@ -228,14 +512,12 @@ func findWorkerBinary() string {
 
 // POST sends a POST request to the worker.
 func POST(port int, path string, body interface{}) (map[string]interface{}, error) {
-	client := &http.Client{Timeout: 10 * time.Second}
-
 	jsonBody, err := json.Marshal(body)
 	if err != nil {
 		return nil, err
 	}
 
-	resp, err := client.Post(
+	resp, err := hookClient.Post(
 		fmt.Sprintf("http://127.0.0.1:%d%s", port, path),
 		"application/json",
 		bytes.NewReader(jsonBody),
@@ -243,7 +525,7 @@ func POST(port int, path string, body interface{}) (map[string]interface{}, erro
 	if err != nil {
 		return nil, err
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode >= 400 {
 		return nil, fmt.Errorf("request failed: %s", resp.Status)
@@ -251,22 +533,44 @@ func POST(port int, path string, body interface{}) (map[string]interface{}, erro
 
 	var result map[string]interface{}
 	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		// Not all endpoints return JSON body - return empty map for success with no body
-		return map[string]interface{}{}, nil
+		// Not all endpoints return JSON
+		return nil, nil
 	}
 
 	return result, nil
 }
 
+// POSTWithContext sends a POST request using the provided context.
+// Used for fire-and-forget calls where we want to control the timeout externally.
+func POSTWithContext(ctx context.Context, port int, path string, body interface{}) error {
+	jsonBody, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		fmt.Sprintf("http://127.0.0.1:%d%s", port, path),
+		bytes.NewReader(jsonBody))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := hookClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	return nil
+}
+
 // GET sends a GET request to the worker.
 func GET(port int, path string) (map[string]interface{}, error) {
-	client := &http.Client{Timeout: 10 * time.Second}
-
-	resp, err := client.Get(fmt.Sprintf("http://127.0.0.1:%d%s", port, path))
+	resp, err := hookClient.Get(fmt.Sprintf("http://127.0.0.1:%d%s", port, path))
 	if err != nil {
 		return nil, err
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode >= 400 {
 		return nil, fmt.Errorf("request failed: %s", resp.Status)

pkg/hooks/worker_test.go

@@ -2,6 +2,7 @@
 package hooks
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -517,8 +518,9 @@ func TestProjectIDWithName_Uniqueness(t *testing.T) {
 // TestHookConstants tests hook-related constants.
 func TestHookConstants(t *testing.T) {
 	assert.Equal(t, 37777, DefaultWorkerPort)
-	assert.Equal(t, 1*time.Second, HealthCheckTimeout)
-	assert.Equal(t, 30*time.Second, StartupTimeout)
+	assert.Equal(t, 2*time.Second, HealthCheckTimeout)
+	assert.Equal(t, 10*time.Second, StartupTimeout)
+	assert.Equal(t, 15*time.Second, EnsureWorkerDeadline)
 }
 
 // TestExitCodes tests exit code constants.
@@ -1200,5 +1202,104 @@ func TestHealthCheckTimeout(t *testing.T) {
 // TestStartupTimeout tests the startup timeout is reasonable.
 func TestStartupTimeout(t *testing.T) {
 	assert.Greater(t, StartupTimeout, 5*time.Second)
-	assert.LessOrEqual(t, StartupTimeout, time.Minute)
+	assert.LessOrEqual(t, StartupTimeout, 15*time.Second)
+}
+
+// TestEnsureWorkerDeadline tests the deadline is within hook budget.
+func TestEnsureWorkerDeadline(t *testing.T) {
+	assert.Greater(t, EnsureWorkerDeadline, StartupTimeout, "deadline must exceed startup timeout")
+	assert.LessOrEqual(t, EnsureWorkerDeadline, 20*time.Second, "deadline must fit in hook timeout budget")
+}
+
+// --- Regression tests for Fixes 1, 3, 4 ---
+
+// TestEnsureWorkerRunning_RespectsDeadline verifies that EnsureWorkerRunning returns
+// within a bounded time even in worst case (no worker, startup fails).
+func TestEnsureWorkerRunning_RespectsDeadline(t *testing.T) {
+	// Reset circuit breaker so the function actually tries to start.
+	circuitBreakerMu.Lock()
+	lastStartupFailure = time.Time{}
+	circuitBreakerMu.Unlock()
+
+	// Use a port that nothing listens on.
+	t.Setenv("CLAUDE_MNEMONIC_WORKER_PORT", "19999")
+	// Point HOME to a temp dir so findWorkerBinary finds nothing.
+	t.Setenv("HOME", t.TempDir())
+	// Clear plugin root to avoid that path too.
+	t.Setenv("CLAUDE_PLUGIN_ROOT", "")
+
+	start := time.Now()
+	_, err := EnsureWorkerRunning()
+	elapsed := time.Since(start)
+
+	// Must error (no binary found).
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "worker binary not found")
+	// Must complete well within EnsureWorkerDeadline.
+	assert.Less(t, elapsed, EnsureWorkerDeadline,
+		"EnsureWorkerRunning took %v, exceeding deadline %v", elapsed, EnsureWorkerDeadline)
+}
+
+// TestEnsureWorkerRunningCtx_CancelledContext verifies immediate return on cancelled context.
+func TestEnsureWorkerRunningCtx_CancelledContext(t *testing.T) {
+	// Reset circuit breaker.
+	circuitBreakerMu.Lock()
+	lastStartupFailure = time.Time{}
+	circuitBreakerMu.Unlock()
+
+	t.Setenv("CLAUDE_MNEMONIC_WORKER_PORT", "19998")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // cancel immediately
+
+	start := time.Now()
+	_, err := ensureWorkerRunningCtx(ctx)
+	elapsed := time.Since(start)
+
+	assert.Error(t, err)
+	assert.Less(t, elapsed, 1*time.Second, "cancelled context should return immediately")
+}
+
+// TestSleepCtx_Normal verifies sleepCtx completes normally.
+func TestSleepCtx_Normal(t *testing.T) {
+	ctx := context.Background()
+	start := time.Now()
+	err := sleepCtx(ctx, 50*time.Millisecond)
+	elapsed := time.Since(start)
+
+	assert.NoError(t, err)
+	assert.GreaterOrEqual(t, elapsed, 50*time.Millisecond)
+}
+
+// TestSleepCtx_Cancelled verifies sleepCtx returns early on cancel.
+func TestSleepCtx_Cancelled(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	start := time.Now()
+	err := sleepCtx(ctx, 5*time.Second)
+	elapsed := time.Since(start)
+
+	assert.Error(t, err)
+	assert.Less(t, elapsed, 500*time.Millisecond)
+}
+
+// TestHookClients_DisableKeepAlives asserts shared clients disable keep-alives
+// to prevent TIME_WAIT connection leaks in short-lived hook processes.
+func TestHookClients_DisableKeepAlives(t *testing.T) {
+	hTransport, ok := hookClient.Transport.(*http.Transport)
+	require.True(t, ok, "hookClient.Transport should be *http.Transport")
+	assert.True(t, hTransport.DisableKeepAlives, "hookClient must disable keep-alives")
+	assert.Equal(t, 1, hTransport.MaxIdleConns)
+
+	hcTransport, ok := healthClient.Transport.(*http.Transport)
+	require.True(t, ok, "healthClient.Transport should be *http.Transport")
+	assert.True(t, hcTransport.DisableKeepAlives, "healthClient must disable keep-alives")
+	assert.Equal(t, 1, hcTransport.MaxIdleConns)
+}
+
+// TestHookClient_Timeout verifies hookClient timeout is set.
+func TestHookClient_Timeout(t *testing.T) {
+	assert.Equal(t, 10*time.Second, hookClient.Timeout)
+	assert.Equal(t, HealthCheckTimeout, healthClient.Timeout)
 }

pkg/sanitize/sanitize.go

@@ -0,0 +1,63 @@
+// Package sanitize provides content cleaning utilities for stripping
+// Claude Code internal XML artifacts from captured text.
+package sanitize
+
+import (
+	"regexp"
+	"strings"
+)
+
+// systemXMLTags lists Claude Code internal XML tags that should be stripped
+// from captured content before processing. These are system-level artifacts
+// that pollute observations and summaries when stored.
+var systemXMLTags = []string{
+	// Claude Code task/agent system
+	"task-notification",
+	// System reminders injected by Claude Code
+	"system-reminder",
+	// Claude-mnemonic's own context injection
+	"relevant-memory",
+	// Hook output wrappers
+	"user-prompt-submit-hook",
+	// Large output persistence
+	"persisted-output",
+	// Tool loading system
+	"available-deferred-tools",
+	// Fast mode info
+	"fast_mode_info",
+	// Anthropic internal
+	"antml_thinking",
+	"antml_function_calls",
+}
+
+// systemXMLRegexps are compiled regexps for each tag, built once at init.
+var systemXMLRegexps []*regexp.Regexp
+
+func init() {
+	systemXMLRegexps = make([]*regexp.Regexp, len(systemXMLTags))
+	for i, tag := range systemXMLTags {
+		// Match opening tag (with optional attributes), content (including newlines), and closing tag
+		systemXMLRegexps[i] = regexp.MustCompile(`(?s)<` + regexp.QuoteMeta(tag) + `[^>]*>.*?</` + regexp.QuoteMeta(tag) + `>`)
+	}
+}
+
+// StripSystemXML removes known Claude Code internal XML blocks from text.
+// This prevents system artifacts like <task-notification>, <system-reminder>,
+// and <relevant-memory> from being stored in observations and summaries.
+func StripSystemXML(s string) string {
+	// Quick check: if no angle brackets, nothing to strip
+	if !strings.Contains(s, "<") {
+		return s
+	}
+
+	for _, re := range systemXMLRegexps {
+		s = re.ReplaceAllString(s, "")
+	}
+
+	// Clean up resulting double-blank-lines from removed blocks
+	for strings.Contains(s, "\n\n\n") {
+		s = strings.ReplaceAll(s, "\n\n\n", "\n\n")
+	}
+
+	return strings.TrimSpace(s)
+}

pkg/sanitize/sanitize_test.go

@@ -0,0 +1,113 @@
+package sanitize
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestStripSystemXML(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "no XML tags",
+			input:    "Hello, this is plain text with no XML.",
+			expected: "Hello, this is plain text with no XML.",
+		},
+		{
+			name:     "empty string",
+			input:    "",
+			expected: "",
+		},
+		{
+			name:  "task-notification block",
+			input: "Before\n<task-notification>\n<task-id>abc123</task-id>\n<status>completed</status>\n<summary>Agent completed</summary>\n<result>Some result text</result>\n</task-notification>\nAfter",
+			expected: "Before\n\nAfter",
+		},
+		{
+			name:     "system-reminder block",
+			input:    "Content before\n<system-reminder>\nSome system reminder text\n</system-reminder>\nContent after",
+			expected: "Content before\n\nContent after",
+		},
+		{
+			name:     "relevant-memory block",
+			input:    "<relevant-memory>\n# Relevant Knowledge\n## 1. Something\n</relevant-memory>\nActual content",
+			expected: "Actual content",
+		},
+		{
+			name:     "system-reminder with attributes",
+			input:    "Before <system-reminder type=\"hook\">reminder text</system-reminder> After",
+			expected: "Before  After",
+		},
+		{
+			name:     "multiple different tags",
+			input:    "Start\n<task-notification><status>done</status></task-notification>\nMiddle\n<system-reminder>reminder</system-reminder>\nEnd",
+			expected: "Start\n\nMiddle\n\nEnd",
+		},
+		{
+			name:     "persisted-output block",
+			input:    "Result: <persisted-output>\nLarge output stored at: /tmp/foo\n</persisted-output> done",
+			expected: "Result:  done",
+		},
+		{
+			name:     "available-deferred-tools block",
+			input:    "<available-deferred-tools>\nTool1\nTool2\n</available-deferred-tools>\nUser message",
+			expected: "User message",
+		},
+		{
+			name:     "fast_mode_info block",
+			input:    "Text <fast_mode_info>\nFast mode uses same model\n</fast_mode_info> more text",
+			expected: "Text  more text",
+		},
+		{
+			name:     "preserves non-system XML",
+			input:    "<observation><type>bugfix</type><title>Fixed thing</title></observation>",
+			expected: "<observation><type>bugfix</type><title>Fixed thing</title></observation>",
+		},
+		{
+			name:     "no angle brackets fast path",
+			input:    "Just plain text without any special characters",
+			expected: "Just plain text without any special characters",
+		},
+		{
+			name:     "collapses triple newlines",
+			input:    "Before\n<system-reminder>x</system-reminder>\n\n\nAfter",
+			expected: "Before\n\nAfter",
+		},
+		{
+			name:  "real-world task notification",
+			input: "Here is the analysis:\n<task-notification>\n<task-id>a077fd04aed547ce1</task-id>\n<tool-use-id>toolu_01Kw2GwsArQQR1F9aV3VfzhP</tool-use-id>\n<status>completed</status>\n<summary>Agent \"Analyze agency-agents repo structure\" completed</summary>\n<result>Now I have all the information I need. Let me compile a comprehensive report.\n\n## Agency-Agents Directory Exploration Report\n\n### 1. Agent File Count and Organization\n\n**Total Agent Files (excluding strategy docs):** 61 agents across 9 categories</result>\n</task-notification>\nThe repo has 61 agents.",
+			expected: "Here is the analysis:\n\nThe repo has 61 agents.",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := StripSystemXML(tt.input)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func BenchmarkStripSystemXML(b *testing.B) {
+	// Text with no XML (fast path)
+	b.Run("no_xml", func(b *testing.B) {
+		text := "This is plain text without any XML tags at all."
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			StripSystemXML(text)
+		}
+	})
+
+	// Text with system XML to strip
+	b.Run("with_xml", func(b *testing.B) {
+		text := "Before\n<task-notification>\n<task-id>abc</task-id>\n<status>done</status>\n</task-notification>\n<system-reminder>reminder text here</system-reminder>\nAfter"
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			StripSystemXML(text)
+		}
+	})
+}

plugin/.claude-plugin/plugin.json.tpl

@@ -5,5 +5,14 @@
   "author": {
     "name": "lukaszraczylo",
     "email": "[email protected]"
-  }
+  },
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": {
+    "claude-mnemonic": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-server",
+      "args": ["--project", "${CLAUDE_PROJECT}"],
+      "env": {}
+    }
+  },
+  "commands": ["./commands/restart.md"]
 }

scripts/download-models.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Download ONNX models from Hugging Face for local development and CI.
+# Usage: ./scripts/download-models.sh [--force]
+#
+# Downloads models to internal/*/assets/ for go:embed and to testdata/models/
+# for Go tests (CLAUDE_MNEMONIC_MODEL_DIR points there).
+
+set -e
+
+ASSETS_EMB="internal/embedding/assets"
+ASSETS_RERANK="internal/reranking/assets"
+TESTDATA="testdata/models"
+FORCE_DOWNLOAD=false
+
+for arg in "$@"; do
+	if [ "$arg" = "--force" ]; then
+		FORCE_DOWNLOAD=true
+	fi
+done
+
+download_if_needed() {
+	local url="$1"
+	local dest="$2"
+	local name="$3"
+	local expected_sha="$4"
+
+	if [ "$FORCE_DOWNLOAD" = false ] && [ -f "$dest" ]; then
+		local actual_sha
+		actual_sha=$(shasum -a 256 "$dest" | awk '{print $1}')
+		if [ "$actual_sha" = "$expected_sha" ]; then
+			echo "[skip] $name"
+			return
+		fi
+		echo "[mismatch] $name checksum mismatch, re-downloading"
+	fi
+
+	echo "[download] $name ($(basename "$url"))"
+	curl -fsSL --retry 3 --retry-delay 2 "$url" -o "$dest"
+	echo "[ok] $name"
+}
+
+echo "=== Downloading models from Hugging Face ==="
+
+# BGE-small-en-v1.5 embedding model (~127 MB)
+download_if_needed \
+	"https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx" \
+	"${ASSETS_EMB}/model.onnx" \
+	"embedding (bge-small-en-v1.5)" \
+	"828e1496d7fabb79cfa4dcd84fa38625c0d3d21da474a00f08db0f559940cf35"
+
+# MS-MARCO MiniLM-L6-v2 cross-encoder model (~91 MB)
+download_if_needed \
+	"https://huggingface.co/cross-encoder/ms-marco-MiniLM-L6-v2/resolve/main/onnx/model.onnx" \
+	"${ASSETS_RERANK}/model.onnx" \
+	"cross-encoder (ms-marco-MiniLM-L6-v2)" \
+	"5d3e70fd0c9ff14b9b5169a51e957b7a9c74897afd0a35ce4bd318150c1d4d4a"
+
+echo ""
+echo "=== Staging models for tests ==="
+mkdir -p "${TESTDATA}"
+cp "${ASSETS_EMB}/model.onnx" "${TESTDATA}/bge-small-en-v1.5-model.onnx"
+cp "${ASSETS_RERANK}/model.onnx" "${TESTDATA}/ms-marco-MiniLM-L6-v2-model.onnx"
+echo "[ok] Test models staged to ${TESTDATA}/"
+
+echo "Done!"

scripts/download-onnx-libs.sh

@@ -6,7 +6,7 @@
 
 set -e
 
-ONNX_VERSION="1.23.2"
+ONNX_VERSION="1.26.0"
 ASSETS_DIR="internal/embedding/assets/lib"
 PLATFORM="${1:-all}"
 FORCE_DOWNLOAD=false

scripts/install.sh

@@ -7,6 +7,8 @@
 
 set -e
 
+INSTALLER_VERSION="1.1.0"
+
 # Configuration
 GITHUB_REPO="lukaszraczylo/claude-mnemonic"
 INSTALL_DIR="$HOME/.claude/plugins/marketplaces/claude-mnemonic"
@@ -40,6 +42,50 @@ error() {
     exit 1
 }
 
+# Gracefully stop worker processes (SIGTERM first, then SIGKILL after timeout)
+graceful_stop_worker() {
+    # Send SIGTERM first
+    pkill -TERM -f 'claude-mnemonic.*worker' 2>/dev/null || true
+    pkill -TERM -f '\.claude/plugins/.*/worker' 2>/dev/null || true
+    if command -v lsof &> /dev/null; then
+        lsof -ti :37777 2>/dev/null | xargs kill -TERM 2>/dev/null || true
+    elif command -v ss &> /dev/null; then
+        ss -tlnp 'sport = :37777' 2>/dev/null | awk 'NR>1 {print $6}' | grep -oP 'pid=\K[0-9]+' | xargs -r kill -TERM 2>/dev/null || true
+    elif command -v fuser &> /dev/null; then
+        fuser -k -TERM 37777/tcp 2>/dev/null || true
+    fi
+
+    # Wait up to 5 seconds for graceful shutdown
+    local waited=0
+    while [[ $waited -lt 5 ]]; do
+        if ! pgrep -f 'claude-mnemonic.*worker' &>/dev/null && ! pgrep -f '\.claude/plugins/.*/worker' &>/dev/null; then
+            return 0
+        fi
+        sleep 1
+        waited=$((waited + 1))
+    done
+
+    # Force kill if still running
+    pkill -9 -f 'claude-mnemonic.*worker' 2>/dev/null || true
+    pkill -9 -f '\.claude/plugins/.*/worker' 2>/dev/null || true
+    if command -v lsof &> /dev/null; then
+        lsof -ti :37777 2>/dev/null | xargs kill -9 2>/dev/null || true
+    elif command -v ss &> /dev/null; then
+        ss -tlnp 'sport = :37777' 2>/dev/null | awk 'NR>1 {print $6}' | grep -oP 'pid=\K[0-9]+' | xargs -r kill -9 2>/dev/null || true
+    elif command -v fuser &> /dev/null; then
+        fuser -k 37777/tcp 2>/dev/null || true
+    fi
+    sleep 1
+
+    # Remove stale PID cache to prevent hooks from using old worker info
+    rm -f "$HOME/.claude-mnemonic/.worker-cache" 2>/dev/null || true
+
+    # Verify process is gone
+    if pgrep -f 'claude-mnemonic.*worker' &>/dev/null; then
+        warn "Could not stop existing worker process"
+    fi
+}
+
 # Detect OS and architecture
 detect_platform() {
     local os arch
@@ -131,7 +177,7 @@ download_release() {
     local tmp_dir
 
     tmp_dir=$(mktemp -d)
-    trap "rm -rf $tmp_dir" EXIT
+    trap 'rm -rf "$tmp_dir"' EXIT
 
     # Construct download URL (use .zip for Windows, .tar.gz for others)
     local archive_ext="tar.gz"
@@ -147,8 +193,38 @@ download_release() {
         error "Failed to download release from: $download_url"
     fi
 
+    # Verify download integrity via checksum
+    local checksums_url="https://github.com/${GITHUB_REPO}/releases/download/${version}/checksums.txt"
+    info "Verifying download integrity..."
+    if curl -fsSL -o "$tmp_dir/checksums.txt" "$checksums_url" 2>/dev/null; then
+        local expected_hash actual_hash
+        expected_hash=$(grep "${archive_name}" "$tmp_dir/checksums.txt" | awk '{print $1}')
+        if [[ -z "$expected_hash" ]]; then
+            warn "Archive ${archive_name} not found in checksums.txt, skipping verification"
+        else
+            if command -v shasum &> /dev/null; then
+                actual_hash=$(shasum -a 256 "$tmp_dir/release.${archive_ext}" | awk '{print $1}')
+            elif command -v sha256sum &> /dev/null; then
+                actual_hash=$(sha256sum "$tmp_dir/release.${archive_ext}" | awk '{print $1}')
+            else
+                warn "No SHA256 tool found (shasum or sha256sum), skipping checksum verification"
+                actual_hash=""
+            fi
+            if [[ -n "$actual_hash" ]]; then
+                if [[ "$expected_hash" != "$actual_hash" ]]; then
+                    error "Checksum verification failed! Expected: $expected_hash Got: $actual_hash"
+                fi
+                success "Checksum verified"
+            fi
+        fi
+    else
+        warn "No checksum file available, skipping verification"
+    fi
     info "Extracting archive..."
     if [[ "$archive_ext" == "zip" ]]; then
+        if ! command -v unzip &> /dev/null; then
+            error "unzip is required for Windows archives but not installed"
+        fi
         if ! unzip -q "$tmp_dir/release.zip" -d "$tmp_dir"; then
             error "Failed to extract archive"
         fi
@@ -160,17 +236,7 @@ download_release() {
 
     # Stop existing worker if running
     info "Stopping existing worker (if running)..."
-    pkill -9 -f 'claude-mnemonic.*worker' 2>/dev/null || true
-    pkill -9 -f '\.claude/plugins/.*/worker' 2>/dev/null || true
-    # Kill process on port 37777 (use lsof on macOS, ss/fuser on Linux)
-    if command -v lsof &> /dev/null; then
-        lsof -ti :37777 | xargs kill -9 2>/dev/null || true
-    elif command -v ss &> /dev/null; then
-        ss -tlnp 'sport = :37777' 2>/dev/null | awk 'NR>1 {print $6}' | grep -oP 'pid=\K[0-9]+' | xargs -r kill -9 2>/dev/null || true
-    elif command -v fuser &> /dev/null; then
-        fuser -k 37777/tcp 2>/dev/null || true
-    fi
-    sleep 1
+    graceful_stop_worker
 
     # Create installation directories
     info "Installing to ${INSTALL_DIR}..."
@@ -178,13 +244,21 @@ download_release() {
     mkdir -p "$INSTALL_DIR/.claude-plugin"
     mkdir -p "$INSTALL_DIR/commands"
 
-    # Copy binaries
-    cp "$tmp_dir/worker" "$INSTALL_DIR/"
-    cp "$tmp_dir/mcp-server" "$INSTALL_DIR/"
-    cp "$tmp_dir/hooks/"* "$INSTALL_DIR/hooks/"
+    # Copy binaries (abort on failure — could indicate disk full or permissions issue)
+    if ! cp "$tmp_dir/worker" "$INSTALL_DIR/"; then
+        error "Failed to copy worker binary to $INSTALL_DIR/"
+    fi
+    if ! cp "$tmp_dir/mcp-server" "$INSTALL_DIR/"; then
+        error "Failed to copy mcp-server binary to $INSTALL_DIR/"
+    fi
+    if ! cp "$tmp_dir/hooks/"* "$INSTALL_DIR/hooks/"; then
+        error "Failed to copy hook binaries to $INSTALL_DIR/hooks/"
+    fi
 
     # Copy plugin configuration
-    cp "$tmp_dir/.claude-plugin/"* "$INSTALL_DIR/.claude-plugin/"
+    if ! cp "$tmp_dir/.claude-plugin/"* "$INSTALL_DIR/.claude-plugin/"; then
+        error "Failed to copy plugin configuration to $INSTALL_DIR/.claude-plugin/"
+    fi
 
     # Copy slash commands if they exist in the release
     if [[ -d "$tmp_dir/commands" ]]; then
@@ -338,72 +412,51 @@ start_worker() {
         error "Worker binary not found at $worker_path"
     fi
 
+    # Check for port conflict with a non-mnemonic process
+    if command -v lsof &> /dev/null; then
+        local port_pid
+        port_pid=$(lsof -ti :37777 2>/dev/null || true)
+        if [[ -n "$port_pid" ]]; then
+            local port_cmd
+            port_cmd=$(ps -p "$port_pid" -o comm= 2>/dev/null || true)
+            if [[ -n "$port_cmd" ]] && ! echo "$port_cmd" | grep -q "worker"; then
+                warn "Port 37777 is in use by another process: $port_cmd (PID $port_pid)"
+                warn "The worker may fail to start. Consider stopping the conflicting process."
+            fi
+        fi
+    fi
+
     info "Starting worker service..."
     nohup "$worker_path" > /tmp/claude-mnemonic-worker.log 2>&1 &
 
-    sleep 2
+    # Retry health check up to 5 times with 1s interval
+    local retries=0
+    local max_retries=5
+    while [[ $retries -lt $max_retries ]]; do
+        sleep 1
+        if curl -sS http://localhost:37777/health > /dev/null 2>&1; then
+            success "Worker started successfully at http://localhost:37777"
+            return 0
+        fi
+        retries=$((retries + 1))
+    done
 
-    if curl -sS http://localhost:37777/health > /dev/null 2>&1; then
-        success "Worker started successfully at http://localhost:37777"
-    else
-        warn "Worker may not have started properly. Check /tmp/claude-mnemonic-worker.log"
-    fi
+    warn "Worker may not have started properly after ${max_retries} attempts. Check /tmp/claude-mnemonic-worker.log"
 }
 
 # Check optional dependencies for semantic search
 check_optional_deps() {
-    local missing_deps=()
-    local install_hints=""
+    # Semantic search uses embedded ONNX runtime - no external Python/uvx dependencies needed
+    success "Semantic search enabled (embedded ONNX runtime)"
+}
 
-    # Check for Python 3.13+
-    if command -v python3 &> /dev/null; then
-        local py_version=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null)
-        if [[ "$py_version" < "3.13" ]]; then
-            missing_deps+=("Python 3.13+ (found $py_version)")
-        fi
-    else
-        missing_deps+=("Python 3.13+")
-    fi
-
-    # Check for uvx
-    if ! command -v uvx &> /dev/null; then
-        missing_deps+=("uvx")
-    fi
-
-    if [[ ${#missing_deps[@]} -gt 0 ]]; then
-        echo ""
-        warn "Optional dependencies missing (needed for semantic search):"
-        for dep in "${missing_deps[@]}"; do
-            echo "  - $dep"
-        done
-        echo ""
-
-        # Detect OS and show appropriate install command
-        case "$(uname -s)" in
-            Darwin)
-                info "Install on macOS:"
-                echo "  brew install [email protected]"
-                echo "  pip3 install uv"
-                ;;
-            Linux)
-                info "Install on Linux:"
-                echo "  sudo apt install python3 python3-pip"
-                echo "  pip3 install uv"
-                ;;
-            MINGW*|MSYS*|CYGWIN*)
-                info "Install on Windows:"
-                echo "  winget install Python.Python.3.13"
-                echo "  pip install uv"
-                ;;
-        esac
-        echo ""
-        info "Note: Requires Python 3.13+. Most package managers install the latest version."
-        echo ""
-        info "Semantic search will be disabled until these are installed."
-        info "Core functionality (SQLite storage, full-text search) will work."
-        echo ""
-    else
-        success "Optional dependencies found (semantic search enabled)"
+# Rollback partially installed files on failure
+INSTALL_COMPLETE=false
+cleanup_on_failure() {
+    if [[ "$INSTALL_COMPLETE" != "true" ]]; then
+        warn "Installation did not complete — cleaning up partial install..."
+        rm -rf "$INSTALL_DIR" 2>/dev/null || true
+        rm -rf "$CACHE_DIR" 2>/dev/null || true
     fi
 }
 
@@ -411,6 +464,8 @@ check_optional_deps() {
 main() {
     local version="${1:-}"
 
+    trap cleanup_on_failure EXIT
+
     echo ""
     echo "╔═══════════════════════════════════════════════════════════╗"
     echo "║           Claude Mnemonic - Installation Script           ║"
@@ -455,6 +510,8 @@ main() {
     # Check optional dependencies
     check_optional_deps
 
+    INSTALL_COMPLETE=true
+
     echo ""
     echo "╔═══════════════════════════════════════════════════════════╗"
     echo "║                  Installation Complete!                   ║"
@@ -467,6 +524,12 @@ main() {
     echo ""
 }
 
+# Handle --version flag
+if [[ "${1:-}" == "--version" ]]; then
+    echo "claude-mnemonic installer v${INSTALLER_VERSION}"
+    exit 0
+fi
+
 # Handle --register-only flag
 if [[ "${1:-}" == "--register-only" ]]; then
     version=$(cat "$INSTALL_DIR/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | sed -E 's/.*"([^"]+)".*/\1/' || echo "1.0.0")
@@ -486,17 +549,7 @@ if [[ "${1:-}" == "--uninstall" ]]; then
     echo ""
 
     info "Stopping worker processes..."
-    pkill -9 -f 'claude-mnemonic.*worker' 2>/dev/null || true
-    pkill -9 -f '\.claude/plugins/.*/worker' 2>/dev/null || true
-    # Kill process on port 37777 (use lsof on macOS, ss/fuser on Linux)
-    if command -v lsof &> /dev/null; then
-        lsof -ti :37777 | xargs kill -9 2>/dev/null || true
-    elif command -v ss &> /dev/null; then
-        ss -tlnp 'sport = :37777' 2>/dev/null | awk 'NR>1 {print $6}' | grep -oP 'pid=\K[0-9]+' | xargs -r kill -9 2>/dev/null || true
-    elif command -v fuser &> /dev/null; then
-        fuser -k 37777/tcp 2>/dev/null || true
-    fi
-    sleep 1
+    graceful_stop_worker
 
     info "Removing plugin directories..."
     rm -rf "$INSTALL_DIR"

scripts/register-plugin.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
 # Register claude-mnemonic plugin with Claude Code
+# Ensures plugin survives CLI updates via extraKnownMarketplaces in settings.json
 
 set -e
 
@@ -9,6 +10,7 @@ MARKETPLACES_FILE="$HOME/.claude/plugins/known_marketplaces.json"
 PLUGIN_KEY="claude-mnemonic@claude-mnemonic"
 MARKETPLACE_NAME="claude-mnemonic"
 MARKETPLACE_PATH="$HOME/.claude/plugins/marketplaces/claude-mnemonic"
+STABLE_BIN="$HOME/.claude-mnemonic/bin"
 
 # Get version from git tags (same as Makefile), or use argument if provided
 VERSION="${1:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}"
@@ -16,6 +18,36 @@ CACHE_BASE="$HOME/.claude/plugins/cache/claude-mnemonic/claude-mnemonic"
 CACHE_PATH="$CACHE_BASE/$VERSION"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
 
+# Helper: safely write JSON via tmp file with validation
+# Usage: safe_jq_write <jq_args...> <input_file>
+# The last argument is treated as the input file, output goes to input_file.tmp
+safe_jq_write() {
+    local args=("$@")
+    local last_idx=$((${#args[@]} - 1))
+    local input_file="${args[$last_idx]}"
+    local tmp_file="${input_file}.tmp"
+
+    if jq "${args[@]}" > "$tmp_file"; then
+        if jq . "$tmp_file" > /dev/null 2>&1; then
+            mv "$tmp_file" "$input_file"
+        else
+            echo "ERROR: jq produced invalid JSON for $input_file, aborting"
+            rm -f "$tmp_file"
+            return 1
+        fi
+    else
+        echo "ERROR: jq failed for $input_file, aborting"
+        rm -f "$tmp_file"
+        return 1
+    fi
+}
+
+# Check that Claude Code directory exists
+if [ ! -d "$HOME/.claude" ]; then
+    echo "Warning: $HOME/.claude directory not found. Claude Code may not be installed."
+    echo "Continuing anyway, but plugin may not function until Claude Code is installed."
+fi
+
 # Ensure plugins directory exists
 mkdir -p "$HOME/.claude/plugins"
 
@@ -40,15 +72,122 @@ if [ ! -f "$MARKETPLACES_FILE" ]; then
     echo '{}' > "$MARKETPLACES_FILE"
 fi
 
-# Check if jq is available
-if command -v jq &> /dev/null; then
-    # Ensure cache directory exists and copy plugin files
-    mkdir -p "$CACHE_PATH/.claude-plugin"
-    mkdir -p "$CACHE_PATH/hooks"
-    mkdir -p "$CACHE_PATH/commands"
+# Ensure cache directory exists and copy plugin files (wrapper scripts + metadata)
+mkdir -p "$CACHE_PATH/.claude-plugin"
+mkdir -p "$CACHE_PATH/hooks"
+mkdir -p "$CACHE_PATH/commands"
 
-    # Copy files from marketplace to cache
+# Copy wrapper scripts and metadata from marketplace to cache
+if [ -d "$MARKETPLACE_PATH" ]; then
     cp -r "$MARKETPLACE_PATH/"* "$CACHE_PATH/" 2>/dev/null || true
+fi
+
+# Also ensure actual binaries are available via the wrapper scripts
+# The wrappers delegate to $STABLE_BIN which has the real binaries
+if [ ! -x "$STABLE_BIN/mcp-server" ]; then
+    echo "WARNING: Binaries not found at $STABLE_BIN. Run 'make install' from the source directory."
+fi
+
+# --- JSON registration ---
+# Uses jq if available, falls back to python3 for systems without jq.
+
+STATUSLINE_CMD="\${CLAUDE_PLUGIN_ROOT}/hooks/statusline"
+
+# Helper: register plugin using python3 (jq-free fallback)
+register_with_python() {
+    python3 - "$PLUGINS_FILE" "$SETTINGS_FILE" "$MARKETPLACES_FILE" \
+        "$PLUGIN_KEY" "$CACHE_PATH" "$VERSION" "$TIMESTAMP" \
+        "$STATUSLINE_CMD" "$MARKETPLACE_NAME" "$MARKETPLACE_PATH" <<'PYEOF'
+import json, sys, os
+
+plugins_file, settings_file, marketplaces_file = sys.argv[1], sys.argv[2], sys.argv[3]
+plugin_key, cache_path, version, timestamp = sys.argv[4], sys.argv[5], sys.argv[6], sys.argv[7]
+statusline_cmd, marketplace_name, marketplace_path = sys.argv[8], sys.argv[9], sys.argv[10]
+
+def load_json(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, FileNotFoundError):
+        return {}
+
+def save_json(path, data):
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+
+# 1. installed_plugins.json
+plugins = load_json(plugins_file)
+plugins.setdefault("version", 2)
+plugins.setdefault("plugins", {})
+plugins["plugins"][plugin_key] = [{
+    "scope": "user",
+    "installPath": cache_path,
+    "version": version,
+    "installedAt": timestamp,
+    "lastUpdated": timestamp
+}]
+save_json(plugins_file, plugins)
+print("Plugin registered in installed_plugins.json")
+
+# 2. settings.json — enable plugin AND add to extraKnownMarketplaces for persistence
+settings = load_json(settings_file)
+settings.setdefault("enabledPlugins", {})
+settings["enabledPlugins"][plugin_key] = True
+settings["statusLine"] = {
+    "type": "command",
+    "command": statusline_cmd,
+    "padding": 0
+}
+# extraKnownMarketplaces ensures plugin survives Claude Code CLI updates
+settings.setdefault("extraKnownMarketplaces", {})
+settings["extraKnownMarketplaces"][marketplace_name] = {
+    "source": {
+        "repo": "lukaszraczylo/claude-mnemonic",
+        "source": "github"
+    }
+}
+save_json(settings_file, settings)
+print("Plugin enabled in settings.json")
+print("Added to extraKnownMarketplaces for persistence")
+print("Statusline configured in settings.json")
+
+# 3. known_marketplaces.json
+marketplaces = load_json(marketplaces_file)
+marketplaces[marketplace_name] = {
+    "source": {
+        "source": "github",
+        "repo": "lukaszraczylo/claude-mnemonic"
+    },
+    "installLocation": marketplace_path,
+    "lastUpdated": timestamp
+}
+save_json(marketplaces_file, marketplaces)
+print("Marketplace registered in known_marketplaces.json")
+PYEOF
+}
+
+# Detect JSON tool and register
+if command -v jq &> /dev/null; then
+    # Validate jq version (1.6+ required for //= operator)
+    JQ_VERSION=$(jq --version 2>/dev/null | sed 's/jq-//')
+    JQ_MAJOR=$(echo "$JQ_VERSION" | cut -d. -f1)
+    JQ_MINOR=$(echo "$JQ_VERSION" | cut -d. -f2)
+    if [ -n "$JQ_MAJOR" ] && [ -n "$JQ_MINOR" ]; then
+        if [ "$JQ_MAJOR" -lt 1 ] || { [ "$JQ_MAJOR" -eq 1 ] && [ "$JQ_MINOR" -lt 6 ]; }; then
+            echo "jq $JQ_VERSION found but too old (need 1.6+), trying python3..."
+            if command -v python3 &> /dev/null; then
+                register_with_python
+            else
+                echo "ERROR: jq 1.6+ or python3 is required for plugin registration"
+                exit 1
+            fi
+            echo "Plugin registered successfully using python3"
+            exit 0
+        fi
+    fi
 
     # Use jq for proper JSON manipulation
     PLUGIN_ENTRY=$(cat <<EOF
@@ -57,22 +196,18 @@ if command -v jq &> /dev/null; then
     "installPath": "$CACHE_PATH",
     "version": "$VERSION",
     "installedAt": "$TIMESTAMP",
-    "lastUpdated": "$TIMESTAMP",
-    "isLocal": true
+    "lastUpdated": "$TIMESTAMP"
 }]
 EOF
 )
 
     # Add or update the plugin entry in installed_plugins.json
-    jq --arg key "$PLUGIN_KEY" --argjson entry "$PLUGIN_ENTRY" \
-        '.plugins[$key] = $entry' "$PLUGINS_FILE" > "${PLUGINS_FILE}.tmp" \
-        && mv "${PLUGINS_FILE}.tmp" "$PLUGINS_FILE"
+    safe_jq_write --arg key "$PLUGIN_KEY" --argjson entry "$PLUGIN_ENTRY" \
+        '.plugins[$key] = $entry' "$PLUGINS_FILE"
 
     echo "Plugin registered in installed_plugins.json"
 
-    # Enable the plugin in settings.json and configure statusline
-    # First ensure enabledPlugins object exists, then add our plugin
-    STATUSLINE_CMD="$MARKETPLACE_PATH/hooks/statusline"
+    # Enable the plugin in settings.json, configure statusline, and add to extraKnownMarketplaces
     STATUSLINE_ENTRY=$(cat <<EOF
 {
     "type": "command",
@@ -82,19 +217,30 @@ EOF
 EOF
 )
 
-    jq --arg key "$PLUGIN_KEY" --argjson statusline "$STATUSLINE_ENTRY" \
-        '.enabledPlugins //= {} | .enabledPlugins[$key] = true | .statusLine = $statusline' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" \
-        && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
+    MARKETPLACE_SOURCE=$(cat <<EOF
+{
+    "source": {
+        "repo": "lukaszraczylo/claude-mnemonic",
+        "source": "github"
+    }
+}
+EOF
+)
+
+    safe_jq_write --arg key "$PLUGIN_KEY" --argjson statusline "$STATUSLINE_ENTRY" \
+        --arg mkname "$MARKETPLACE_NAME" --argjson mksource "$MARKETPLACE_SOURCE" \
+        '.enabledPlugins //= {} | .enabledPlugins[$key] = true | .statusLine = $statusline | .extraKnownMarketplaces //= {} | .extraKnownMarketplaces[$mkname] = $mksource' "$SETTINGS_FILE"
 
     echo "Plugin enabled in settings.json"
+    echo "Added to extraKnownMarketplaces for persistence"
     echo "Statusline configured in settings.json"
 
-    # Register the marketplace in known_marketplaces.json
+    # Register the marketplace in known_marketplaces.json (GitHub source)
     MARKETPLACE_ENTRY=$(cat <<EOF
 {
     "source": {
-        "source": "directory",
-        "path": "$MARKETPLACE_PATH"
+        "source": "github",
+        "repo": "lukaszraczylo/claude-mnemonic"
     },
     "installLocation": "$MARKETPLACE_PATH",
     "lastUpdated": "$TIMESTAMP"
@@ -102,45 +248,17 @@ EOF
 EOF
 )
 
-    jq --arg key "$MARKETPLACE_NAME" --argjson entry "$MARKETPLACE_ENTRY" \
-        '.[$key] = $entry' "$MARKETPLACES_FILE" > "${MARKETPLACES_FILE}.tmp" \
-        && mv "${MARKETPLACES_FILE}.tmp" "$MARKETPLACES_FILE"
+    safe_jq_write --arg key "$MARKETPLACE_NAME" --argjson entry "$MARKETPLACE_ENTRY" \
+        '.[$key] = $entry' "$MARKETPLACES_FILE"
 
     echo "Marketplace registered in known_marketplaces.json"
-
-    # Register MCP server in settings.json
-    MCP_BINARY="$MARKETPLACE_PATH/mcp-server"
-    if [ -f "$MCP_BINARY" ]; then
-        echo "Registering MCP server in settings.json..."
-
-        # MCP server entry - note the escaped ${CLAUDE_PROJECT}
-        MCP_ENTRY=$(cat <<'EOF'
-{
-    "command": "MCP_BINARY_PLACEHOLDER",
-    "args": ["--project", "${CLAUDE_PROJECT}"],
-    "env": {}
-}
-EOF
-)
-        # Replace placeholder with actual path
-        MCP_ENTRY=$(echo "$MCP_ENTRY" | sed "s|MCP_BINARY_PLACEHOLDER|$MCP_BINARY|g")
-
-        # Add or update mcpServers field
-        if jq --arg key "claude-mnemonic" --argjson entry "$MCP_ENTRY" \
-            '.mcpServers //= {} | .mcpServers[$key] = $entry' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp"; then
-            mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
-            echo "MCP server registered successfully"
-        else
-            echo "Warning: Failed to register MCP server (jq error)"
-            rm -f "${SETTINGS_FILE}.tmp"
-        fi
-    else
-        echo "MCP server binary not found at $MCP_BINARY, skipping MCP registration"
-    fi
-
     echo "Plugin registered successfully using jq"
+
+elif command -v python3 &> /dev/null; then
+    register_with_python
+    echo "Plugin registered successfully using python3"
 else
-    echo "ERROR: jq is required for plugin registration"
-    echo "Please install jq: brew install jq (macOS) or apt-get install jq (Linux)"
+    echo "ERROR: jq or python3 is required for plugin registration"
+    echo "Please install one: brew install jq (macOS) or apt-get install jq (Linux)"
     exit 1
 fi

scripts/unregister-plugin.sh

@@ -3,6 +3,18 @@
 
 set -e
 
+# Stop running worker processes before removing binaries
+echo "Stopping worker processes..."
+pkill -TERM -f 'claude-mnemonic.*worker' 2>/dev/null || true
+pkill -TERM -f '\.claude/plugins/.*/worker' 2>/dev/null || true
+sleep 2
+# Force kill if still running
+pkill -9 -f 'claude-mnemonic.*worker' 2>/dev/null || true
+pkill -9 -f '\.claude/plugins/.*/worker' 2>/dev/null || true
+# Clean up port
+lsof -ti :37777 | xargs kill -9 2>/dev/null || true
+sleep 1
+
 PLUGINS_FILE="$HOME/.claude/plugins/installed_plugins.json"
 SETTINGS_FILE="$HOME/.claude/settings.json"
 MARKETPLACES_FILE="$HOME/.claude/plugins/known_marketplaces.json"
@@ -30,16 +42,17 @@ else
     echo "No plugins file found, skipping"
 fi
 
-# Remove from settings.json (enabledPlugins and statusLine if it points to our plugin)
+# Remove from settings.json (enabledPlugins, statusLine, and mcpServers)
 if [ -f "$SETTINGS_FILE" ]; then
-    # Remove from enabledPlugins and clear statusLine if it references our plugin
+    # Remove from enabledPlugins, clear statusLine if it references our plugin, and remove MCP server
     jq --arg key "$PLUGIN_KEY" '
         del(.enabledPlugins[$key]) |
         if .statusLine.command and (.statusLine.command | contains("claude-mnemonic")) then
             del(.statusLine)
         else
             .
-        end
+        end |
+        del(.mcpServers["claude-mnemonic"])
     ' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" \
         && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
     echo "Plugin removed from settings.json"

ui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mnemonic-dashboard",
-  "version": "v0.10.5-15-g385d05a-dirty",
+  "version": "v0.11.57-dirty",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mnemonic-dashboard",
-      "version": "v0.10.5-15-g385d05a-dirty",
+      "version": "v0.11.57-dirty",
       "dependencies": {
         "vis-data": "^7.1.9",
         "vis-network": "^9.1.9",
@@ -625,9 +625,9 @@
       }
     },
     "node_modules/@rollup/rollup-android-arm-eabi": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.53.3.tgz",
-      "integrity": "sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
+      "integrity": "sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==",
       "cpu": [
         "arm"
       ],
@@ -639,9 +639,9 @@
       ]
     },
     "node_modules/@rollup/rollup-android-arm64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.53.3.tgz",
-      "integrity": "sha512-CbDGaMpdE9sh7sCmTrTUyllhrg65t6SwhjlMJsLr+J8YjFuPmCEjbBSx4Z/e4SmDyH3aB5hGaJUP2ltV/vcs4w==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.4.tgz",
+      "integrity": "sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==",
       "cpu": [
         "arm64"
       ],
@@ -653,9 +653,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-arm64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.53.3.tgz",
-      "integrity": "sha512-Nr7SlQeqIBpOV6BHHGZgYBuSdanCXuw09hon14MGOLGmXAFYjx1wNvquVPmpZnl0tLjg25dEdr4IQ6GgyToCUA==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.4.tgz",
+      "integrity": "sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==",
       "cpu": [
         "arm64"
       ],
@@ -667,9 +667,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-x64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.53.3.tgz",
-      "integrity": "sha512-DZ8N4CSNfl965CmPktJ8oBnfYr3F8dTTNBQkRlffnUarJ2ohudQD17sZBa097J8xhQ26AwhHJ5mvUyQW8ddTsQ==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.4.tgz",
+      "integrity": "sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==",
       "cpu": [
         "x64"
       ],
@@ -681,9 +681,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-arm64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.53.3.tgz",
-      "integrity": "sha512-yMTrCrK92aGyi7GuDNtGn2sNW+Gdb4vErx4t3Gv/Tr+1zRb8ax4z8GWVRfr3Jw8zJWvpGHNpss3vVlbF58DZ4w==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.4.tgz",
+      "integrity": "sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==",
       "cpu": [
         "arm64"
       ],
@@ -695,9 +695,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-x64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.53.3.tgz",
-      "integrity": "sha512-lMfF8X7QhdQzseM6XaX0vbno2m3hlyZFhwcndRMw8fbAGUGL3WFMBdK0hbUBIUYcEcMhVLr1SIamDeuLBnXS+Q==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.4.tgz",
+      "integrity": "sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==",
       "cpu": [
         "x64"
       ],
@@ -709,9 +709,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.53.3.tgz",
-      "integrity": "sha512-k9oD15soC/Ln6d2Wv/JOFPzZXIAIFLp6B+i14KhxAfnq76ajt0EhYc5YPeX6W1xJkAdItcVT+JhKl1QZh44/qw==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.4.tgz",
+      "integrity": "sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==",
       "cpu": [
         "arm"
       ],
@@ -723,9 +723,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.53.3.tgz",
-      "integrity": "sha512-vTNlKq+N6CK/8UktsrFuc+/7NlEYVxgaEgRXVUVK258Z5ymho29skzW1sutgYjqNnquGwVUObAaxae8rZ6YMhg==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.4.tgz",
+      "integrity": "sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==",
       "cpu": [
         "arm"
       ],
@@ -737,9 +737,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.53.3.tgz",
-      "integrity": "sha512-RGrFLWgMhSxRs/EWJMIFM1O5Mzuz3Xy3/mnxJp/5cVhZ2XoCAxJnmNsEyeMJtpK+wu0FJFWz+QF4mjCA7AUQ3w==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.4.tgz",
+      "integrity": "sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==",
       "cpu": [
         "arm64"
       ],
@@ -751,9 +751,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-musl": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.53.3.tgz",
-      "integrity": "sha512-kASyvfBEWYPEwe0Qv4nfu6pNkITLTb32p4yTgzFCocHnJLAHs+9LjUu9ONIhvfT/5lv4YS5muBHyuV84epBo/A==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.4.tgz",
+      "integrity": "sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==",
       "cpu": [
         "arm64"
       ],
@@ -765,9 +765,23 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.53.3.tgz",
-      "integrity": "sha512-JiuKcp2teLJwQ7vkJ95EwESWkNRFJD7TQgYmCnrPtlu50b4XvT5MOmurWNrCj3IFdyjBQ5p9vnrX4JM6I8OE7g==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.4.tgz",
+      "integrity": "sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.4.tgz",
+      "integrity": "sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==",
       "cpu": [
         "loong64"
       ],
@@ -779,9 +793,23 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.53.3.tgz",
-      "integrity": "sha512-EoGSa8nd6d3T7zLuqdojxC20oBfNT8nexBbB/rkxgKj5T5vhpAQKKnD+h3UkoMuTyXkP5jTjK/ccNRmQrPNDuw==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.4.tgz",
+      "integrity": "sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.4.tgz",
+      "integrity": "sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==",
       "cpu": [
         "ppc64"
       ],
@@ -793,9 +821,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.53.3.tgz",
-      "integrity": "sha512-4s+Wped2IHXHPnAEbIB0YWBv7SDohqxobiiPA1FIWZpX+w9o2i4LezzH/NkFUl8LRci/8udci6cLq+jJQlh+0g==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.4.tgz",
+      "integrity": "sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==",
       "cpu": [
         "riscv64"
       ],
@@ -807,9 +835,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-musl": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.53.3.tgz",
-      "integrity": "sha512-68k2g7+0vs2u9CxDt5ktXTngsxOQkSEV/xBbwlqYcUrAVh6P9EgMZvFsnHy4SEiUl46Xf0IObWVbMvPrr2gw8A==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.4.tgz",
+      "integrity": "sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==",
       "cpu": [
         "riscv64"
       ],
@@ -821,9 +849,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-s390x-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.53.3.tgz",
-      "integrity": "sha512-VYsFMpULAz87ZW6BVYw3I6sWesGpsP9OPcyKe8ofdg9LHxSbRMd7zrVrr5xi/3kMZtpWL/wC+UIJWJYVX5uTKg==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.4.tgz",
+      "integrity": "sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==",
       "cpu": [
         "s390x"
       ],
@@ -835,9 +863,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.53.3.tgz",
-      "integrity": "sha512-3EhFi1FU6YL8HTUJZ51imGJWEX//ajQPfqWLI3BQq4TlvHy4X0MOr5q3D2Zof/ka0d5FNdPwZXm3Yyib/UEd+w==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==",
       "cpu": [
         "x64"
       ],
@@ -849,9 +877,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-musl": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.53.3.tgz",
-      "integrity": "sha512-eoROhjcc6HbZCJr+tvVT8X4fW3/5g/WkGvvmwz/88sDtSJzO7r/blvoBDgISDiCjDRZmHpwud7h+6Q9JxFwq1Q==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.4.tgz",
+      "integrity": "sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==",
       "cpu": [
         "x64"
       ],
@@ -862,10 +890,24 @@
         "linux"
       ]
     },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.4.tgz",
+      "integrity": "sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
     "node_modules/@rollup/rollup-openharmony-arm64": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.53.3.tgz",
-      "integrity": "sha512-OueLAWgrNSPGAdUdIjSWXw+u/02BRTcnfw9PN41D2vq/JSEPnJnVuBgw18VkN8wcd4fjUs+jFHVM4t9+kBSNLw==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.4.tgz",
+      "integrity": "sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==",
       "cpu": [
         "arm64"
       ],
@@ -877,9 +919,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-arm64-msvc": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.53.3.tgz",
-      "integrity": "sha512-GOFuKpsxR/whszbF/bzydebLiXIHSgsEUp6M0JI8dWvi+fFa1TD6YQa4aSZHtpmh2/uAlj/Dy+nmby3TJ3pkTw==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.4.tgz",
+      "integrity": "sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==",
       "cpu": [
         "arm64"
       ],
@@ -891,9 +933,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-ia32-msvc": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.53.3.tgz",
-      "integrity": "sha512-iah+THLcBJdpfZ1TstDFbKNznlzoxa8fmnFYK4V67HvmuNYkVdAywJSoteUszvBQ9/HqN2+9AZghbajMsFT+oA==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.4.tgz",
+      "integrity": "sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==",
       "cpu": [
         "ia32"
       ],
@@ -905,9 +947,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-gnu": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.53.3.tgz",
-      "integrity": "sha512-J9QDiOIZlZLdcot5NXEepDkstocktoVjkaKUtqzgzpt2yWjGlbYiKyp05rWwk4nypbYUNoFAztEgixoLaSETkg==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==",
       "cpu": [
         "x64"
       ],
@@ -919,9 +961,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-msvc": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.53.3.tgz",
-      "integrity": "sha512-UhTd8u31dXadv0MopwGgNOBpUVROFKWVQgAg5N1ESyCz8AuBcMqm4AuTjrwgQKGDfoFuz02EuMRHQIw/frmYKQ==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.4.tgz",
+      "integrity": "sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==",
       "cpu": [
         "x64"
       ],
@@ -1239,9 +1281,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
-      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz",
+      "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1765,13 +1807,13 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -1800,9 +1842,9 @@
       }
     },
     "node_modules/nanoid": {
-      "version": "3.3.11",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
-      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
       "funding": [
         {
           "type": "github",
@@ -1885,9 +1927,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -1918,9 +1960,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.6",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
-      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
       "funding": [
         {
           "type": "opencollective",
@@ -1937,7 +1979,7 @@
       ],
       "license": "MIT",
       "dependencies": {
-        "nanoid": "^3.3.11",
+        "nanoid": "^3.3.12",
         "picocolors": "^1.1.1",
         "source-map-js": "^1.2.1"
       },
@@ -2156,9 +2198,9 @@
       }
     },
     "node_modules/rollup": {
-      "version": "4.53.3",
-      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.53.3.tgz",
-      "integrity": "sha512-w8GmOxZfBmKknvdXU1sdM9NHcoQejwF/4mNgj2JuEEdRaHwwF12K7e9eXn1nLZ07ad+du76mkVsyeb2rKGllsA==",
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
+      "integrity": "sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2172,28 +2214,31 @@
         "npm": ">=8.0.0"
       },
       "optionalDependencies": {
-        "@rollup/rollup-android-arm-eabi": "4.53.3",
-        "@rollup/rollup-android-arm64": "4.53.3",
-        "@rollup/rollup-darwin-arm64": "4.53.3",
-        "@rollup/rollup-darwin-x64": "4.53.3",
-        "@rollup/rollup-freebsd-arm64": "4.53.3",
-        "@rollup/rollup-freebsd-x64": "4.53.3",
-        "@rollup/rollup-linux-arm-gnueabihf": "4.53.3",
-        "@rollup/rollup-linux-arm-musleabihf": "4.53.3",
-        "@rollup/rollup-linux-arm64-gnu": "4.53.3",
-        "@rollup/rollup-linux-arm64-musl": "4.53.3",
-        "@rollup/rollup-linux-loong64-gnu": "4.53.3",
-        "@rollup/rollup-linux-ppc64-gnu": "4.53.3",
-        "@rollup/rollup-linux-riscv64-gnu": "4.53.3",
-        "@rollup/rollup-linux-riscv64-musl": "4.53.3",
-        "@rollup/rollup-linux-s390x-gnu": "4.53.3",
-        "@rollup/rollup-linux-x64-gnu": "4.53.3",
-        "@rollup/rollup-linux-x64-musl": "4.53.3",
-        "@rollup/rollup-openharmony-arm64": "4.53.3",
-        "@rollup/rollup-win32-arm64-msvc": "4.53.3",
-        "@rollup/rollup-win32-ia32-msvc": "4.53.3",
-        "@rollup/rollup-win32-x64-gnu": "4.53.3",
-        "@rollup/rollup-win32-x64-msvc": "4.53.3",
+        "@rollup/rollup-android-arm-eabi": "4.60.4",
+        "@rollup/rollup-android-arm64": "4.60.4",
+        "@rollup/rollup-darwin-arm64": "4.60.4",
+        "@rollup/rollup-darwin-x64": "4.60.4",
+        "@rollup/rollup-freebsd-arm64": "4.60.4",
+        "@rollup/rollup-freebsd-x64": "4.60.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.4",
+        "@rollup/rollup-linux-arm64-musl": "4.60.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.4",
+        "@rollup/rollup-linux-loong64-musl": "4.60.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-musl": "4.60.4",
+        "@rollup/rollup-openbsd-x64": "4.60.4",
+        "@rollup/rollup-openharmony-arm64": "4.60.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.4",
+        "@rollup/rollup-win32-x64-gnu": "4.60.4",
+        "@rollup/rollup-win32-x64-msvc": "4.60.4",
         "fsevents": "~2.3.2"
       }
     },
@@ -2363,9 +2408,9 @@
       }
     },
     "node_modules/tinyglobby/node_modules/picomatch": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
-      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2455,9 +2500,9 @@
       "license": "MIT"
     },
     "node_modules/uuid": {
-      "version": "11.1.0",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
-      "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
+      "version": "11.1.1",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.1.tgz",
+      "integrity": "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==",
       "funding": [
         "https://github.com/sponsors/broofa",
         "https://github.com/sponsors/ctavan"
@@ -2519,9 +2564,9 @@
       }
     },
     "node_modules/vite": {
-      "version": "6.4.1",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz",
-      "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
+      "version": "6.4.2",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.2.tgz",
+      "integrity": "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2612,9 +2657,9 @@
       }
     },
     "node_modules/vite/node_modules/picomatch": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
-      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
       "engines": {

ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mnemonic-dashboard",
-  "version": "v0.10.5-15-g385d05a-dirty",
+  "version": "v0.11.57-dirty",
   "private": true,
   "type": "module",
   "scripts": {

workflow-prepare.sh

@@ -10,46 +10,62 @@ HOST_OS=$(uname -s | tr '[:upper:]' '[:lower:]')
 # Determine target platform for ONNX library download
 # Use TARGET_GOOS/TARGET_GOARCH from CI matrix if available, otherwise auto-detect
 if [ -n "$TARGET_GOOS" ] && [ -n "$TARGET_GOARCH" ]; then
-    ONNX_PLATFORM="${TARGET_GOOS}-${TARGET_GOARCH}"
-    echo "Target platform from CI matrix: $ONNX_PLATFORM"
+	ONNX_PLATFORM="${TARGET_GOOS}-${TARGET_GOARCH}"
+	echo "Target platform from CI matrix: $ONNX_PLATFORM"
 else
-    ONNX_PLATFORM="auto"
+	ONNX_PLATFORM="auto"
 fi
 
 # On Windows, install SQLite development headers for CGO
 if [[ "$HOST_OS" == mingw* ]] || [[ "$HOST_OS" == msys* ]] || [[ "$HOST_OS" == cygwin* ]]; then
-    echo "Installing SQLite for Windows..."
+	echo "Installing SQLite for Windows..."
 
-    # Download SQLite amalgamation and set up for CGO
-    SQLITE_VERSION="3470200"
-    SQLITE_YEAR="2024"
-    SQLITE_DIR="/c/sqlite"
-    SQLITE_URL="https://www.sqlite.org/${SQLITE_YEAR}/sqlite-amalgamation-${SQLITE_VERSION}.zip"
+	# Download SQLite amalgamation and set up for CGO
+	SQLITE_VERSION="3470200"
+	SQLITE_YEAR="2024"
+	SQLITE_DIR="/c/sqlite"
+	SQLITE_URL="https://www.sqlite.org/${SQLITE_YEAR}/sqlite-amalgamation-${SQLITE_VERSION}.zip"
 
-    mkdir -p "$SQLITE_DIR"
-    curl -sSL "$SQLITE_URL" -o /tmp/sqlite.zip
-    unzip -q /tmp/sqlite.zip -d /tmp/
-    cp /tmp/sqlite-amalgamation-${SQLITE_VERSION}/* "$SQLITE_DIR/"
-    rm -rf /tmp/sqlite.zip /tmp/sqlite-amalgamation-${SQLITE_VERSION}
+	mkdir -p "$SQLITE_DIR"
+	curl -sSL "$SQLITE_URL" -o /tmp/sqlite.zip
+	unzip -q /tmp/sqlite.zip -d /tmp/
+	cp /tmp/sqlite-amalgamation-${SQLITE_VERSION}/* "$SQLITE_DIR/"
+	rm -rf /tmp/sqlite.zip /tmp/sqlite-amalgamation-${SQLITE_VERSION}
 
-    # Download Go modules first so we can patch sqlite-vec
-    echo "Downloading Go modules..."
-    go mod download
+	# Download Go modules first so we can patch sqlite-vec
+	echo "Downloading Go modules..."
+	go mod download
 
-    # Find the sqlite-vec module and copy sqlite3.h there
-    SQLITE_VEC_PATH=$(go list -m -f '{{.Dir}}' github.com/asg017/sqlite-vec-go-bindings 2>/dev/null || true)
-    if [ -n "$SQLITE_VEC_PATH" ] && [ -d "$SQLITE_VEC_PATH/cgo" ]; then
-        # Make module writable (it's read-only by default)
-        chmod -R u+w "$SQLITE_VEC_PATH"
-        cp "$SQLITE_DIR/sqlite3.h" "$SQLITE_VEC_PATH/cgo/"
-        cp "$SQLITE_DIR/sqlite3.c" "$SQLITE_VEC_PATH/cgo/"
-        echo "SQLite headers copied to $SQLITE_VEC_PATH/cgo/"
-    fi
+	# Find the sqlite-vec module and copy sqlite3.h there
+	SQLITE_VEC_PATH=$(go list -m -f '{{.Dir}}' github.com/asg017/sqlite-vec-go-bindings 2>/dev/null || true)
+	if [ -n "$SQLITE_VEC_PATH" ] && [ -d "$SQLITE_VEC_PATH/cgo" ]; then
+		# Make module writable (it's read-only by default)
+		chmod -R u+w "$SQLITE_VEC_PATH"
+		cp "$SQLITE_DIR/sqlite3.h" "$SQLITE_VEC_PATH/cgo/"
+		cp "$SQLITE_DIR/sqlite3.c" "$SQLITE_VEC_PATH/cgo/"
+		echo "SQLite headers copied to $SQLITE_VEC_PATH/cgo/"
+	fi
 
-    # Tell linker to allow multiple definitions (both go-sqlite3 and sqlite-vec embed SQLite)
-    echo "CGO_LDFLAGS=-Wl,--allow-multiple-definition" >> "$GITHUB_ENV"
-    echo "SQLite setup complete"
+	# Tell linker to allow multiple definitions (both go-sqlite3 and sqlite-vec embed SQLite)
+	echo "CGO_LDFLAGS=-Wl,--allow-multiple-definition" >>"$GITHUB_ENV"
+	echo "SQLite setup complete"
 fi
 
 # Download ONNX runtime libraries for target platform
 ./scripts/download-onnx-libs.sh "$ONNX_PLATFORM"
+
+# Download ONNX models from Hugging Face and stage for tests
+# Non-fatal: if download fails, tests will attempt runtime download themselves
+set +e
+./scripts/download-models.sh
+DOWNLOAD_EXIT=$?
+set -e
+
+if [ $DOWNLOAD_EXIT -eq 0 ]; then
+	# Export model directory so tests can find models without network access
+	if [ -n "$GITHUB_ENV" ]; then
+		echo "CLAUDE_MNEMONIC_MODEL_DIR=$GITHUB_WORKSPACE/testdata/models" >>"$GITHUB_ENV"
+	fi
+else
+	echo "Warning: Model download failed — tests will try to download models at runtime"
+fi