claude_memory 0.9.1 → 0.10.0

data/lib/claude_memory/dashboard/conflicts.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Conflicts resource for the dashboard API. Owns list/detail/reject
+    # across both scopes (global + project) and keeps them disjoint — a
+    # conflict in one store can never reference a fact in the other.
+    #
+    # List results are deduplicated at the display layer by
+    # (source, predicate, normalized(object_a, object_b), status). Each group
+    # carries a `group_size` so the UI can label "sqlite vs postgres (×11)"
+    # instead of surfacing 11 rows that resolve identically. `counts` reflects
+    # the distinct count; `raw_counts` preserves the underlying row totals for
+    # the Advanced drawer.
+    class Conflicts
+      DEFAULT_LIMIT = 50
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param params [Hash] "scope" (project|global|all), "status"
+      #   (open|resolved|all), "limit", "offset"
+      def list(params = {})
+        scope = params["scope"] || "project"
+        status_filter = params["status"] || "open"
+        limit = (params["limit"] || DEFAULT_LIMIT).to_i
+        offset = (params["offset"] || 0).to_i
+
+        stores = stores_for(scope)
+        rows = stores.flat_map { |source, store|
+          dataset = store.conflicts
+          dataset = dataset.where(status: status_filter) unless status_filter == "all"
+          dataset.all.map { |r| r.merge(source: source, store: store) }
+        }
+
+        groups = group_rows(rows)
+        groups.sort_by! { |g| -Core::RelativeTime.to_epoch(g[:representative][:detected_at]) }
+
+        {
+          total: groups.size,
+          limit: limit,
+          offset: offset,
+          scope: scope,
+          status: status_filter,
+          counts: counts_across_scopes,
+          raw_counts: raw_counts_across_scopes,
+          conflicts: Array(groups[offset, limit]).map { |g| serialize_group(g) }
+        }
+      end
+
+      # Count distinct open conflicts per scope (after deduplication). Used by
+      # Trust#needs_review so the sidebar backlog reflects distinct pairs
+      # rather than duplicated rows from pre-dedupe history.
+      def distinct_open_counts
+        counts = {project: 0, global: 0}
+        %w[project global].each do |scope|
+          store = @manager.store_if_exists(scope)
+          next unless store
+          rows = store.conflicts.where(status: "open").all
+            .map { |r| r.merge(source: scope, store: store) }
+          counts[scope.to_sym] = group_rows(rows).size
+        end
+        counts.merge(total: counts.values.sum)
+      end
+
+      # @param id [Integer, String] conflict row id
+      # @param scope [String] "project" or "global" (required — conflicts are scope-local)
+      def detail(id, scope)
+        return {error: "Invalid scope"} unless %w[global project].include?(scope)
+        store = @manager.store_if_exists(scope)
+        return {error: "#{scope} store not available"} unless store
+
+        row = store.conflicts.where(id: id.to_i).first
+        return {error: "Conflict #{id} not found"} unless row
+
+        presenter = FactPresenter.new(store)
+        {
+          conflict: {
+            id: row[:id],
+            status: row[:status],
+            detected_at: row[:detected_at],
+            detected_ago: Core::RelativeTime.format(row[:detected_at]),
+            notes: row[:notes],
+            source: scope
+          },
+          fact_a: presenter.with_provenance(store.facts.where(id: row[:fact_a_id]).first),
+          fact_b: presenter.with_provenance(store.facts.where(id: row[:fact_b_id]).first)
+        }
+      end
+
+      # Rejects one side of a conflict by rejecting its fact. SQLiteStore#reject_fact
+      # flips the fact to "rejected" and cascade-resolves associated conflicts in
+      # a single transaction, so duplicate rows collapse automatically.
+      def reject(id, side:, reason: nil, scope: "project")
+        return {error: "Invalid side (must be 'a' or 'b')"} unless %w[a b].include?(side)
+        return {error: "Invalid scope"} unless %w[global project].include?(scope)
+        store = @manager.store_if_exists(scope)
+        return {error: "#{scope} store not available"} unless store
+
+        row = store.conflicts.where(id: id.to_i).first
+        return {error: "Conflict #{id} not found"} unless row
+
+        fact_id = (side == "a") ? row[:fact_a_id] : row[:fact_b_id]
+        result = store.reject_fact(fact_id, reason: reason)
+
+        {
+          success: true,
+          conflict_id: id,
+          rejected_fact_id: fact_id,
+          side: side,
+          scope: scope,
+          conflicts_resolved: result[:conflicts_resolved]
+        }
+      end
+
+      # Bulk-reject every disputed fact that's in open conflict against a
+      # single "keeper" fact. Resolves the distiller-hallucination pattern
+      # where one correct fact (e.g. uses_database=sqlite) accumulates many
+      # contradicting candidates (postgresql, mysql, redis, ...). For each
+      # open conflict where keeper_fact_id is on either side, the fact on
+      # the OTHER side is rejected; SQLiteStore#reject_fact cascade-resolves
+      # the conflict inside its own transaction.
+      #
+      # @return [Hash] {rejected_fact_ids:, conflicts_resolved:}
+      def reject_similar(keeper_fact_id, reason: nil, scope: "project")
+        return {error: "Invalid scope"} unless %w[global project].include?(scope)
+        store = @manager.store_if_exists(scope)
+        return {error: "#{scope} store not available"} unless store
+
+        keeper_id = keeper_fact_id.to_i
+        rows = store.conflicts
+          .where(status: "open")
+          .where(Sequel.|({fact_a_id: keeper_id}, {fact_b_id: keeper_id}))
+          .all
+
+        return {success: true, keeper_fact_id: keeper_id, rejected_fact_ids: [], conflicts_resolved: 0} if rows.empty?
+
+        rejected = []
+        total_resolved = 0
+        rows.each do |row|
+          loser_id = (row[:fact_a_id] == keeper_id) ? row[:fact_b_id] : row[:fact_a_id]
+          next if rejected.include?(loser_id)
+          result = store.reject_fact(loser_id, reason: reason)
+          rejected << loser_id
+          total_resolved += result[:conflicts_resolved] || 0
+        end
+
+        {
+          success: true,
+          keeper_fact_id: keeper_id,
+          rejected_fact_ids: rejected,
+          conflicts_resolved: total_resolved,
+          scope: scope
+        }
+      end
+
+      private
+
+      def stores_for(scope)
+        case scope
+        when "project"
+          {"project" => @manager.store_if_exists("project")}.compact
+        when "global"
+          {"global" => @manager.store_if_exists("global")}.compact
+        else
+          {
+            "project" => @manager.store_if_exists("project"),
+            "global" => @manager.store_if_exists("global")
+          }.compact
+        end
+      end
+
+      def counts_across_scopes
+        counts = {project: {open: 0, resolved: 0, total: 0},
+                  global: {open: 0, resolved: 0, total: 0}}
+        [:project, :global].each do |source|
+          store = @manager.store_if_exists(source.to_s)
+          next unless store
+          %w[open resolved].each do |status|
+            rows = store.conflicts.where(status: status).all
+              .map { |r| r.merge(source: source.to_s, store: store) }
+            distinct = group_rows(rows).size
+            counts[source][status.to_sym] = distinct
+            counts[source][:total] += distinct
+          end
+        end
+        counts
+      end
+
+      def raw_counts_across_scopes
+        counts = {project: {open: 0, resolved: 0, total: 0},
+                  global: {open: 0, resolved: 0, total: 0}}
+        [:project, :global].each do |source|
+          store = @manager.store_if_exists(source.to_s)
+          next unless store
+          store.conflicts.group_and_count(:status).all.each do |r|
+            key = r[:status].to_sym
+            counts[source][key] = r[:count] if counts[source].key?(key)
+            counts[source][:total] += r[:count]
+          end
+        end
+        counts
+      end
+
+      # Group conflict rows by (source, predicate, normalized(objects), status)
+      # so pre-dedupe historical duplicates collapse into one display row.
+      # Returns [{representative:, members:, facts:}...] — `representative` is
+      # the most recently detected row in the group; `members` is all raw rows;
+      # `facts` maps fact_id → facts-table row for the representative's two
+      # sides (batched to avoid N+1).
+      def group_rows(rows)
+        return [] if rows.empty?
+
+        facts_by_source = load_facts_for_rows(rows)
+
+        groups = {}
+        rows.each do |row|
+          store_facts = facts_by_source[row[:source]] || {}
+          fact_a = store_facts[row[:fact_a_id]]
+          fact_b = store_facts[row[:fact_b_id]]
+          key = grouping_key(row, fact_a, fact_b)
+          groups[key] ||= {members: [], facts: {}}
+          groups[key][:members] << row
+          groups[key][:facts][row[:fact_a_id]] ||= fact_a if fact_a
+          groups[key][:facts][row[:fact_b_id]] ||= fact_b if fact_b
+        end
+
+        groups.values.map do |g|
+          sorted = g[:members].sort_by { |r| -Core::RelativeTime.to_epoch(r[:detected_at]) }
+          {representative: sorted.first, members: g[:members], facts: g[:facts]}
+        end
+      end
+
+      def load_facts_for_rows(rows)
+        by_source = {}
+        rows.group_by { |r| [r[:source], r[:store]] }.each do |(source, store), group|
+          ids = group.flat_map { |r| [r[:fact_a_id], r[:fact_b_id]] }.compact.uniq
+          by_source[source] = ids.empty? ? {} : store.facts.where(id: ids).as_hash(:id)
+        end
+        by_source
+      end
+
+      def grouping_key(row, fact_a, fact_b)
+        predicate = fact_a&.dig(:predicate) || fact_b&.dig(:predicate) || "?"
+        objects = [normalize_object(fact_a), normalize_object(fact_b)].sort
+        [row[:source], row[:status], predicate, *objects]
+      end
+
+      def normalize_object(fact)
+        return "" unless fact
+        (fact[:object_literal] || "").to_s.downcase.strip.gsub(/\s+/, " ")
+      end
+
+      def serialize_group(group)
+        row = group[:representative]
+        store = row[:store]
+        presenter = FactPresenter.new(store)
+        fact_a = group[:facts][row[:fact_a_id]] || store.facts.where(id: row[:fact_a_id]).first
+        fact_b = group[:facts][row[:fact_b_id]] || store.facts.where(id: row[:fact_b_id]).first
+
+        {
+          id: row[:id],
+          fact_a_id: row[:fact_a_id],
+          fact_b_id: row[:fact_b_id],
+          fact_a_preview: presenter.preview(fact_a),
+          fact_b_preview: presenter.preview(fact_b),
+          status: row[:status],
+          detected_at: row[:detected_at],
+          detected_ago: Core::RelativeTime.format(row[:detected_at]),
+          notes: row[:notes],
+          source: row[:source],
+          group_size: group[:members].size,
+          group_member_ids: group[:members].map { |m| m[:id] }
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/efficacy.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    module Efficacy
+      # Pure report calculator for recall activity events. Takes a list of
+      # already-loaded events and produces the shaped metrics the dashboard
+      # renders. No I/O, no database access — separating compute from
+      # loading keeps the aggregation fast-testable and portable across
+      # event sources.
+      #
+      # Expected event shape (matches {ClaudeMemory::ActivityLog.recent} output):
+      #
+      #   {
+      #     id:, event_type:, status:, duration_ms:, session_id:,
+      #     occurred_at:, details: {tool:, query:, result_count:,
+      #                             results_by_scope: {"project" => N, "global" => M}, ...}
+      #   }
+      module Reporter
+        RECALL_TRACE_LIMIT = 50
+        MEMORY_GAPS_LIMIT = 10
+
+        module_function
+
+        # @param events [Array<Hash>] recall activity events (post-filter)
+        # @param timeframe [Hash] {since:, session_id:} echoed into the response
+        # @return [Hash] the efficacy payload
+        def report(events, timeframe: {})
+          result_counts = events.map { |e| e.dig(:details, :result_count) || 0 }
+          latencies = events.map { |e| e[:duration_ms] }.compact
+          successful = events.count { |e| e[:status] == "success" && (e.dig(:details, :result_count) || 0) > 0 }
+          empty = events.count { |e| e[:status] == "success" && (e.dig(:details, :result_count) || 0) == 0 }
+
+          {
+            timeframe: {since: timeframe[:since], session_id: timeframe[:session_id]},
+            recall_events: events.size,
+            successful_recalls: successful,
+            empty_recalls: empty,
+            hit_rate: percentage(successful, events.size),
+            total_results_served: result_counts.sum,
+            median_results_per_query: median(result_counts),
+            median_latency_ms: median(latencies),
+            tool_mix: tool_mix(events),
+            source_contribution: source_contribution(events),
+            memory_gaps: memory_gaps(events),
+            recall_trace: recall_trace(events)
+          }
+        end
+
+        # Percentage with zero-safe denominator, rounded to 1 decimal.
+        def percentage(part, whole)
+          return 0 if whole.to_i.zero?
+          (part.to_f / whole * 100).round(1)
+        end
+
+        # Sorted median — returns 0 for empty input, midpoint average for even counts.
+        def median(values)
+          return 0 if values.empty?
+          sorted = values.sort
+          mid = sorted.size / 2
+          if sorted.size.odd?
+            sorted[mid]
+          else
+            ((sorted[mid - 1] + sorted[mid]) / 2.0).round(1)
+          end
+        end
+
+        def tool_mix(events)
+          events
+            .group_by { |e| e.dig(:details, :tool) || "(unknown)" }
+            .map { |tool, rows|
+              hits = rows.count { |r| (r.dig(:details, :result_count) || 0) > 0 }
+              {
+                tool: tool,
+                count: rows.size,
+                hits: hits,
+                hit_rate: percentage(hits, rows.size)
+              }
+            }
+            .sort_by { |row| -row[:count] }
+        end
+
+        # Aggregate {results_by_scope} across events. Reveals where returned
+        # facts actually came from — the one question only efficacy can answer.
+        def source_contribution(events)
+          totals = Hash.new(0)
+          events.each do |e|
+            by_scope = e.dig(:details, :results_by_scope)
+            next unless by_scope.is_a?(Hash)
+            by_scope.each { |scope, n| totals[scope.to_s] += n.to_i }
+          end
+          totals.empty? ? [] : totals.map { |scope, count| {scope: scope, count: count} }.sort_by { |r| -r[:count] }
+        end
+
+        def memory_gaps(events)
+          events
+            .select { |e| (e.dig(:details, :result_count) || 0).zero? && e.dig(:details, :query) }
+            .first(MEMORY_GAPS_LIMIT)
+            .map { |e|
+              {
+                tool: e.dig(:details, :tool),
+                query: e.dig(:details, :query),
+                occurred_at: e[:occurred_at],
+                occurred_ago: Core::RelativeTime.format(e[:occurred_at])
+              }
+            }
+        end
+
+        def recall_trace(events)
+          events.first(RECALL_TRACE_LIMIT).map { |e|
+            {
+              id: e[:id],
+              tool: e.dig(:details, :tool),
+              query: e.dig(:details, :query),
+              result_count: e.dig(:details, :result_count) || 0,
+              duration_ms: e[:duration_ms],
+              session_id: e[:session_id],
+              status: e[:status],
+              occurred_at: e[:occurred_at],
+              occurred_ago: Core::RelativeTime.format(e[:occurred_at])
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/fact_presenter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Shapes a facts-table row into the hashes the dashboard API emits.
+    # Callers opt in to the shape they need:
+    #
+    # - {#summary}         — full fact with confidence, scope, created_at, created_ago
+    # - {#preview}         — predicate + truncated object for list rows
+    # - {#with_provenance} — summary + provenance chain (quote, session_id, occurred_at)
+    # - {#list_summary}    — batches entity lookups across many rows to avoid N+1
+    #
+    # All methods resolve the subject/object entities from the store passed at
+    # construction time; callers pass in raw facts-table rows (hashes) directly.
+    class FactPresenter
+      OBJECT_PREVIEW_CHARS = 120
+
+      def initialize(store)
+        @store = store
+      end
+
+      # @param row [Hash, nil] a facts-table row
+      # @return [Hash, nil] nil when row is nil
+      def summary(row)
+        return nil unless row
+        serialize(row, load_entities([row[:subject_entity_id], row[:object_entity_id]]))
+      end
+
+      # @param row [Hash, nil]
+      # @return [Hash, nil] object text truncated to {OBJECT_PREVIEW_CHARS}
+      def preview(row)
+        return nil unless row
+        entities = load_entities([row[:subject_entity_id], row[:object_entity_id]])
+        subject = entities[row[:subject_entity_id]]
+        object_entity = entities[row[:object_entity_id]]
+        object_text = row[:object_literal] || object_entity&.dig(:canonical_name) || "unknown"
+        truncated = object_text.to_s.length > OBJECT_PREVIEW_CHARS
+
+        {
+          id: row[:id],
+          docid: row[:docid],
+          subject: subject&.dig(:canonical_name) || "unknown",
+          predicate: row[:predicate],
+          object: truncated ? "#{object_text[0, OBJECT_PREVIEW_CHARS]}…" : object_text,
+          scope: row[:scope],
+          status: row[:status]
+        }
+      end
+
+      # @param row [Hash, nil]
+      # @return [Hash, nil] summary plus :provenance array with session/date context
+      def with_provenance(row)
+        return nil unless row
+        summary(row).merge(provenance: load_provenance(row[:id]))
+      end
+
+      # @param rows [Array<Hash>] facts-table rows
+      # @return [Array<Hash>] summaries with batched entity resolution
+      def list_summary(rows)
+        ids = rows.flat_map { |r| [r[:subject_entity_id], r[:object_entity_id]] }.compact.uniq
+        entities = ids.empty? ? {} : @store.entities.where(id: ids).as_hash(:id)
+        rows.map { |r| serialize(r, entities) }
+      end
+
+      private
+
+      def load_entities(ids)
+        valid = ids.compact.uniq
+        return {} if valid.empty?
+        @store.entities.where(id: valid).as_hash(:id)
+      end
+
+      def load_provenance(fact_id)
+        prov_rows = @store.provenance.where(fact_id: fact_id).all
+        content_ids = prov_rows.map { |p| p[:content_item_id] }.compact.uniq
+        content_items = content_ids.empty? ? {} : @store.content_items.where(id: content_ids).as_hash(:id)
+
+        prov_rows.map { |p|
+          ci = p[:content_item_id] ? content_items[p[:content_item_id]] : nil
+          {
+            quote: p[:quote],
+            strength: p[:strength],
+            content_item_id: p[:content_item_id],
+            session_id: ci&.dig(:session_id),
+            occurred_at: ci&.dig(:occurred_at)
+          }
+        }
+      end
+
+      def serialize(row, entities)
+        subject = entities[row[:subject_entity_id]]
+        object_entity = entities[row[:object_entity_id]]
+        {
+          id: row[:id],
+          docid: row[:docid],
+          subject: subject&.dig(:canonical_name) || "unknown",
+          predicate: row[:predicate],
+          object: row[:object_literal] || object_entity&.dig(:canonical_name) || "unknown",
+          status: row[:status],
+          confidence: row[:confidence],
+          scope: row[:scope],
+          created_at: row[:created_at],
+          created_ago: Core::RelativeTime.format(row[:created_at]),
+          valid_from: row[:valid_from]
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/health.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Dashboard
+    # Aggregates the dashboard "/health" report from four checks: per-database
+    # schema/fact health (global + project), claude-code hooks installation,
+    # and the sqlite-vec vector index. Each check returns a {name, status,
+    # message, fix?} hash; the report's overall status escalates to the
+    # worst individual status (error > warning > healthy).
+    #
+    # Pulled out of Dashboard::API so the wiring lives next to the data
+    # rather than next to the HTTP routing.
+    class Health
+      HOOKS_SETTINGS_PATHS = [".claude/settings.json", ".claude/settings.local.json"].freeze
+      VEC_LOW_COVERAGE_PCT = 10
+      VEC_WARN_COVERAGE_PCT = 50
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      def report
+        checks = [
+          db_check("global", @manager.global_db_path),
+          db_check("project", @manager.project_db_path),
+          hooks_check,
+          vec_check
+        ]
+        {status: aggregate_status(checks), checks: checks, version: ClaudeMemory::VERSION}
+      end
+
+      private
+
+      def aggregate_status(checks)
+        return "error" if checks.any? { |c| c[:status] == "error" }
+        return "warning" if checks.any? { |c| c[:status] == "warning" }
+        "healthy"
+      end
+
+      def db_check(label, path)
+        unless File.exist?(path)
+          return {
+            name: "#{label}_database",
+            status: "warning",
+            message: "Not initialized",
+            fix: "Run `claude-memory init` to create the #{label} database at #{path}."
+          }
+        end
+
+        store = @manager.store_for_scope(label)
+        version = store.schema_version
+        {
+          name: "#{label}_database",
+          status: "healthy",
+          message: "Schema v#{version}, #{store.facts.where(status: "active").count} active facts"
+        }
+      rescue => e
+        {
+          name: "#{label}_database",
+          status: "error",
+          message: e.message,
+          fix: "Inspect the error above. Common causes: corrupt schema, file permissions, or a stale lock. Try `claude-memory recover --scope #{label}`, or remove the file at #{path} and re-run `claude-memory init`."
+        }
+      end
+
+      def hooks_check
+        present = collect_configured_hook_types
+        expected = Commands::Checks::HooksCheck::EXPECTED_HOOKS
+        missing = expected - present
+
+        if present.empty?
+          return {
+            name: "hooks",
+            status: "error",
+            message: "No claude-memory hooks found in #{HOOKS_SETTINGS_PATHS.join(" or ")}",
+            fix: "Run `claude-memory init` to install the standard hook set (#{expected.join(", ")})."
+          }
+        end
+
+        return {name: "hooks", status: "healthy", message: "All #{expected.size} hooks configured"} if missing.empty?
+
+        {
+          name: "hooks",
+          status: "warning",
+          message: "#{present.size}/#{expected.size} hooks configured",
+          fix: "Missing hook(s): #{missing.join(", ")}. Run `claude-memory init` to install the standard set, or add them manually under `hooks.<EventName>[].hooks[]` in .claude/settings.json."
+        }
+      rescue => e
+        {
+          name: "hooks",
+          status: "error",
+          message: e.message,
+          fix: "Failed to read hook settings. Verify .claude/settings.json is valid JSON, then re-run `claude-memory doctor`."
+        }
+      end
+
+      # Walks the two-level hook structure Claude Code uses:
+      # hooks.<EventName>[] -> matcher hash -> .hooks[] -> { type:, command: }
+      def collect_configured_hook_types
+        types = []
+        HOOKS_SETTINGS_PATHS.each do |relpath|
+          path = File.join(Dir.pwd, relpath)
+          next unless File.exist?(path)
+
+          settings = JSON.parse(File.read(path))
+          hooks = settings["hooks"] || {}
+          hooks.each do |event_type, matchers|
+            next unless matchers.is_a?(Array)
+            has_claude_memory = matchers.any? do |matcher|
+              next false unless matcher.is_a?(Hash) && matcher["hooks"].is_a?(Array)
+              matcher["hooks"].any? { |h| h.is_a?(Hash) && h["command"]&.include?("claude-memory") }
+            end
+            types << event_type if has_claude_memory
+          end
+        end
+        types.uniq
+      end
+
+      def vec_check
+        store = @manager.default_store(prefer: :project)
+        unless store
+          return {
+            name: "vectors",
+            status: "warning",
+            message: "No database",
+            fix: "Initialize a database first with `claude-memory init`."
+          }
+        end
+
+        vec = store.vector_index
+        return vec_unavailable_check unless vec.available?
+
+        vec_coverage_check(vec)
+      rescue => e
+        {
+          name: "vectors",
+          status: "warning",
+          message: e.message,
+          fix: "Vector index threw an error. Try `claude-memory index --vec --rebuild` to rebuild from facts."
+        }
+      end
+
+      def vec_unavailable_check
+        {
+          name: "vectors",
+          status: "warning",
+          message: "sqlite-vec not available",
+          fix: "The sqlite-vec extension didn't load. Run `bundle install` to install the gem (>= 0.1.9). Semantic recall will be disabled until this is fixed; lexical recall still works."
+        }
+      end
+
+      def vec_coverage_check(vec)
+        coverage = vec.coverage_stats
+        indexed = coverage[:vec_indexed] || 0
+        total = coverage[:with_embedding] || 0
+        pct = coverage[:coverage_pct] || 0
+        message = (total > 0) ? "#{indexed}/#{total} facts indexed (#{pct}%)" : "0 facts have embeddings yet"
+
+        status = vec_status_for(total, pct)
+        result = {name: "vectors", status: status, message: message}
+        result[:fix] = "Vector coverage is low — run `claude-memory index --vec --rebuild` to regenerate embeddings and reindex all active facts. Semantic recall accuracy degrades as this drops." unless status == "healthy"
+        result
+      end
+
+      def vec_status_for(total, pct)
+        return "healthy" if total.zero?
+        return "error" if pct < VEC_LOW_COVERAGE_PCT
+        return "warning" if pct < VEC_WARN_COVERAGE_PCT
+        "healthy"
+      end
+    end
+  end
+end