claude_memory 0.7.1 → 0.9.0

data/lib/claude_memory/recall.rb

@@ -1,727 +1,175 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
+  # Query interface for facts across dual databases (global + project).
+  # Delegates to DualEngine or LegacyEngine depending on the store type.
   class Recall
+    # @return [String] query only project-scoped facts
     SCOPE_PROJECT = "project"
+    # @return [String] query only global-scoped facts
     SCOPE_GLOBAL = "global"
+    # @return [String] query both project and global facts (default)
     SCOPE_ALL = "all"
 
     class << self
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] recent decision facts
       def recent_decisions(manager, limit: 10)
         Shortcuts.for(:decisions, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] architecture-related facts
       def architecture_choices(manager, limit: 10)
         Shortcuts.for(:architecture, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] convention facts
       def conventions(manager, limit: 20)
         Shortcuts.for(:conventions, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] project configuration facts
       def project_config(manager, limit: 10)
         Shortcuts.for(:project_config, manager, limit: limit)
       end
     end
 
+    # @param store_or_manager [Store::SQLiteStore, Store::StoreManager] database store or dual-database manager
+    # @param fts [Index::LexicalFTS, nil] full-text search index (used only with legacy single-store)
+    # @param project_path [String, nil] project root path (defaults to Configuration#project_dir)
+    # @param env [Hash] environment variables
+    # @param embedding_generator [Object, nil] vector embedding generator for semantic search
     def initialize(store_or_manager, fts: nil, project_path: nil, env: ENV, embedding_generator: nil)
       config = Configuration.new(env)
-      @project_path = project_path || config.project_dir
-      @embedding_generator = embedding_generator || Embeddings::Generator.new
-
-      if store_or_manager.is_a?(Store::StoreManager)
-        @manager = store_or_manager
-        @legacy_mode = false
-      else
-        @legacy_store = store_or_manager
-        @legacy_fts = fts || Index::LexicalFTS.new(store_or_manager)
-        @legacy_mode = true
-      end
-    end
-
-    def query(query_text, limit: 10, scope: SCOPE_ALL, include_raw_text: false)
-      if @legacy_mode
-        query_legacy(query_text, limit: limit, scope: scope)
-      else
-        query_dual(query_text, limit: limit, scope: scope, include_raw_text: include_raw_text)
-      end
-    end
-
-    def query_index(query_text, limit: 20, scope: SCOPE_ALL)
-      if @legacy_mode
-        query_index_legacy(query_text, limit: limit, scope: scope)
+      resolved_project_path = project_path || config.project_dir
+      resolved_generator = embedding_generator || Embeddings.resolve(env: env)
+
+      @engine = if store_or_manager.is_a?(Store::StoreManager)
+        DualEngine.new(
+          store_or_manager,
+          embedding_generator: resolved_generator,
+          project_path: resolved_project_path
+        )
       else
-        query_index_dual(query_text, limit: limit, scope: scope)
-      end
-    end
-
+        LegacyEngine.new(
+          store_or_manager,
+          fts: fts || Index::LexicalFTS.new(store_or_manager),
+          embedding_generator: resolved_generator,
+          project_path: resolved_project_path
+        )
+      end
+    end
+
+    # Search facts by text query using FTS5
+    # @param query_text [String] search terms
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param include_raw_text [Boolean] include source content text in results
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] matching facts with provenance
+    def query(query_text, limit: 10, scope: SCOPE_ALL, include_raw_text: false, intent: nil)
+      @engine.query(query_text, limit: limit, scope: scope, include_raw_text: include_raw_text, intent: intent)
+    end
+
+    # Search content items (not facts) via FTS5 index
+    # @param query_text [String] search terms
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] matching content items
+    def query_index(query_text, limit: 20, scope: SCOPE_ALL, intent: nil)
+      @engine.query_index(query_text, limit: limit, scope: scope, intent: intent)
+    end
+
+    # Traverse fact relationships (supersessions, conflicts) as a graph
+    # @param fact_id [Integer] starting fact ID
+    # @param depth [Integer] traversal depth
+    # @param scope [String, nil] optional scope filter
+    # @return [Hash] graph with nodes and edges
     def fact_graph(fact_id, depth: 2, scope: nil)
-      if @legacy_mode
-        Core::FactGraph.build(@legacy_store, fact_id, depth: depth)
-      else
-        scope ||= SCOPE_PROJECT
-        store = @manager.store_for_scope(scope)
-        Core::FactGraph.build(store, fact_id, depth: depth)
-      end
+      @engine.fact_graph(fact_id, depth: depth, scope: scope)
     end
 
+    # Show provenance chain for a fact
+    # @param fact_id_or_docid [Integer, String] fact ID or document ID
+    # @param scope [String, nil] optional scope filter
+    # @return [Hash] provenance details including source content
     def explain(fact_id_or_docid, scope: nil)
-      if @legacy_mode
-        fact_id = resolve_fact_identifier(@legacy_store, fact_id_or_docid)
-        explain_from_store(@legacy_store, fact_id)
-      else
-        scope ||= SCOPE_PROJECT
-        store = @manager.store_for_scope(scope)
-        fact_id = resolve_fact_identifier(store, fact_id_or_docid)
-        explain_from_store(store, fact_id)
-      end
+      @engine.explain(fact_id_or_docid, scope: scope)
     end
 
+    # List facts created or modified since a given time
+    # @param since [String] ISO 8601 timestamp
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] recently changed facts
     def changes(since:, limit: 50, scope: SCOPE_ALL)
-      if @legacy_mode
-        changes_legacy(since: since, limit: limit, scope: scope)
-      else
-        changes_dual(since: since, limit: limit, scope: scope)
-      end
+      @engine.changes(since: since, limit: limit, scope: scope)
     end
 
+    # List open fact conflicts
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] unresolved conflicts
     def conflicts(scope: SCOPE_ALL)
-      if @legacy_mode
-        conflicts_legacy(scope: scope)
-      else
-        conflicts_dual(scope: scope)
-      end
+      @engine.conflicts(scope: scope)
     end
 
+    # Find facts associated with a git branch
+    # @param branch_name [String] git branch name
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from the given branch
     def facts_by_branch(branch_name, limit: 20, scope: SCOPE_ALL)
-      if @legacy_mode
-        facts_by_context_legacy(:git_branch, branch_name, limit: limit, scope: scope)
-      else
-        facts_by_context_dual(:git_branch, branch_name, limit: limit, scope: scope)
-      end
+      @engine.facts_by_branch(branch_name, limit: limit, scope: scope)
     end
 
+    # Find facts associated with a working directory
+    # @param cwd [String] directory path
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from the given directory
     def facts_by_directory(cwd, limit: 20, scope: SCOPE_ALL)
-      if @legacy_mode
-        facts_by_context_legacy(:cwd, cwd, limit: limit, scope: scope)
-      else
-        facts_by_context_dual(:cwd, cwd, limit: limit, scope: scope)
-      end
+      @engine.facts_by_directory(cwd, limit: limit, scope: scope)
     end
 
+    # Find facts associated with a specific tool
+    # @param tool_name [String] tool name (e.g., "Read", "Bash")
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from sessions using the given tool
     def facts_by_tool(tool_name, limit: 20, scope: SCOPE_ALL)
-      if @legacy_mode
-        facts_by_tool_legacy(tool_name, limit: limit, scope: scope)
-      else
-        facts_by_tool_dual(tool_name, limit: limit, scope: scope)
-      end
-    end
-
-    def query_semantic(text, limit: 10, scope: SCOPE_ALL, mode: :both)
-      if @legacy_mode
-        query_semantic_legacy(text, limit: limit, scope: scope, mode: mode)
-      else
-        query_semantic_dual(text, limit: limit, scope: scope, mode: mode)
-      end
-    end
-
+      @engine.facts_by_tool(tool_name, limit: limit, scope: scope)
+    end
+
+    # Search facts using vector embeddings (semantic similarity)
+    # @param text [String] natural language query
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param mode [Symbol] :vector, :lexical, or :both (hybrid RRF)
+    # @param explain [Boolean] include scoring breakdown in results
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] semantically similar facts
+    def query_semantic(text, limit: 10, scope: SCOPE_ALL, mode: :both, explain: false, intent: nil)
+      @engine.query_semantic(text, limit: limit, scope: scope, mode: mode, explain: explain, intent: intent)
+    end
+
+    # Find facts at the intersection of multiple concepts
+    # @param concepts [Array<String>] 2-5 concept terms to intersect
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts matching all given concepts
+    # @raise [ArgumentError] if concepts count is not 2-5
     def query_concepts(concepts, limit: 10, scope: SCOPE_ALL)
       raise ArgumentError, "Must provide 2-5 concepts" unless (2..5).cover?(concepts.size)
 
-      if @legacy_mode
-        query_concepts_legacy(concepts, limit: limit, scope: scope)
-      else
-        query_concepts_dual(concepts, limit: limit, scope: scope)
-      end
-    end
-
-    private
-
-    def query_dual(query_text, limit:, scope:, include_raw_text: false)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        query_single_store(store, query_text, limit: limit, source: source, include_raw_text: include_raw_text)
-      end
-      dedupe_and_sort(results, limit)
-    end
-
-    def query_index_dual(query_text, limit:, scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        query_index_single_store(store, query_text, limit: limit, source: source)
-      end
-      dedupe_and_sort_index(results, limit)
-    end
-
-    def query_index_single_store(store, query_text, limit:, source:)
-      options = Index::QueryOptions.new(
-        query_text: query_text,
-        limit: limit,
-        scope: :all,
-        source: source
-      )
-
-      query = Index::IndexQuery.new(store, options)
-      query.execute
-    end
-
-    def dedupe_and_sort_index(results, limit)
-      Core::FactRanker.dedupe_and_sort_index(results, limit)
-    end
-
-    def query_single_store(store, query_text, limit:, source:, include_raw_text: false)
-      fts = Index::LexicalFTS.new(store)
-      content_ids = fts.search(query_text, limit: limit * 3)
-      return [] if content_ids.empty?
-
-      # Batch query: fetch ALL provenance records at once using WHERE IN
-      provenance_by_content = store.provenance
-        .select(:fact_id, :content_item_id)
-        .where(content_item_id: content_ids)
-        .all
-        .group_by { |p| p[:content_item_id] }
-
-      # Collect fact IDs in content order, deduplicated
-      ordered_fact_ids = Core::FactCollector.collect_ordered_fact_ids(
-        provenance_by_content,
-        content_ids,
-        limit
-      )
-
-      return [] if ordered_fact_ids.empty?
-
-      # Batch query all facts at once
-      facts_by_id = batch_find_facts(store, ordered_fact_ids)
-
-      # Batch query all receipts at once
-      receipts_by_fact_id = batch_find_receipts(store, ordered_fact_ids, include_raw_text: include_raw_text)
-
-      # Build results maintaining order
-      Core::ResultBuilder.build_results(
-        ordered_fact_ids,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      )
-    end
-
-    def batch_find_facts(store, fact_ids)
-      Core::FactQueryBuilder.batch_find_facts(store, fact_ids)
-    end
-
-    def batch_find_receipts(store, fact_ids, include_raw_text: false)
-      Core::FactQueryBuilder.batch_find_receipts(store, fact_ids, include_raw_text: include_raw_text)
-    end
-
-    def dedupe_and_sort(results, limit)
-      Core::FactRanker.dedupe_and_sort(results, limit)
-    end
-
-    def changes_dual(since:, limit:, scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        changes = fetch_changes(store, since, limit)
-        Core::ResultSorter.annotate_source(changes, source)
-      end
-      Core::ResultSorter.sort_by_timestamp(results, limit)
-    end
-
-    def fetch_changes(store, since, limit)
-      Core::FactQueryBuilder.fetch_changes(store, since, limit)
-    end
-
-    def conflicts_dual(scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      template.execute(scope: scope) do |store, source|
-        conflicts = store.open_conflicts
-        Core::ResultSorter.annotate_source(conflicts, source)
-      end
-    end
-
-    # Resolve a fact identifier to an integer ID
-    # Accepts either an integer ID or an 8-char docid string
-    def resolve_fact_identifier(store, identifier)
-      return identifier if identifier.is_a?(Integer)
-
-      str = identifier.to_s
-      # If it looks like a pure integer, use as ID
-      return str.to_i if str.match?(/\A\d+\z/)
-
-      # Otherwise treat as docid
-      fact = Core::FactQueryBuilder.find_fact_by_docid(store, str)
-      fact ? fact[:id] : nil
-    end
-
-    def explain_from_store(store, fact_id)
-      fact = find_fact_from_store(store, fact_id)
-      return Core::NullExplanation.new unless fact
-
-      {
-        fact: fact,
-        receipts: find_receipts_from_store(store, fact_id),
-        superseded_by: find_superseded_by_from_store(store, fact_id),
-        supersedes: find_supersedes_from_store(store, fact_id),
-        conflicts: find_conflicts_from_store(store, fact_id)
-      }
-    end
-
-    def find_fact_from_store(store, fact_id)
-      Core::FactQueryBuilder.find_fact(store, fact_id)
-    end
-
-    def find_receipts_from_store(store, fact_id)
-      Core::FactQueryBuilder.find_receipts(store, fact_id)
-    end
-
-    def find_superseded_by_from_store(store, fact_id)
-      Core::FactQueryBuilder.find_superseded_by(store, fact_id)
-    end
-
-    def find_supersedes_from_store(store, fact_id)
-      Core::FactQueryBuilder.find_supersedes(store, fact_id)
-    end
-
-    def find_conflicts_from_store(store, fact_id)
-      Core::FactQueryBuilder.find_conflicts(store, fact_id)
-    end
-
-    def query_legacy(query_text, limit:, scope:)
-      content_ids = @legacy_fts.search(query_text, limit: limit * 3)
-      return [] if content_ids.empty?
-
-      # Batch query: fetch ALL provenance records at once using WHERE IN
-      provenance_by_content = @legacy_store.provenance
-        .select(:fact_id, :content_item_id)
-        .where(content_item_id: content_ids)
-        .all
-        .group_by { |p| p[:content_item_id] }
-
-      # Collect ordered unique fact IDs from provenance
-      all_fact_ids = []
-      seen_fact_ids = Set.new
-      content_ids.each do |content_id|
-        (provenance_by_content[content_id] || []).each do |prov|
-          next if seen_fact_ids.include?(prov[:fact_id])
-          seen_fact_ids.add(prov[:fact_id])
-          all_fact_ids << prov[:fact_id]
-        end
-      end
-
-      return [] if all_fact_ids.empty?
-
-      # Batch query: fetch ALL facts at once
-      facts_by_id = batch_find_facts(@legacy_store, all_fact_ids)
-
-      # Filter by scope and apply limit
-      selected_fact_ids = []
-      all_fact_ids.each do |fact_id|
-        fact = facts_by_id[fact_id]
-        next unless fact
-        next unless fact_matches_scope?(fact, scope)
-        selected_fact_ids << fact_id
-        break if selected_fact_ids.size >= limit
-      end
-
-      return [] if selected_fact_ids.empty?
-
-      # Batch query: fetch ALL receipts at once
-      receipts_by_fact_id = batch_find_receipts(@legacy_store, selected_fact_ids)
-
-      facts_with_provenance = selected_fact_ids.map do |fact_id|
-        {
-          fact: facts_by_id[fact_id],
-          receipts: receipts_by_fact_id[fact_id] || []
-        }
-      end
-
-      sort_by_scope_priority(facts_with_provenance)
-    end
-
-    def query_index_legacy(query_text, limit:, scope:)
-      options = Index::QueryOptions.new(
-        query_text: query_text,
-        limit: limit,
-        scope: :all,
-        source: :legacy
-      )
-
-      query = Index::IndexQuery.new(@legacy_store, options)
-      results = query.execute
-
-      # Filter by scope in legacy mode
-      results.select do |result|
-        # Need to get full fact to check scope
-        fact = find_fact(result[:id])
-        fact && fact_matches_scope?(fact, scope)
-      end
-    end
-
-    def changes_legacy(since:, limit:, scope:)
-      ds = @legacy_store.facts
-        .select(:id, :docid, :subject_entity_id, :predicate, :object_literal, :status, :created_at, :scope, :project_path)
-        .where { created_at >= since }
-        .order(Sequel.desc(:created_at))
-        .limit(limit)
-
-      ds = apply_scope_filter(ds, scope)
-      ds.all
-    end
-
-    def conflicts_legacy(scope:)
-      all_conflicts = @legacy_store.open_conflicts
-      return all_conflicts if scope == SCOPE_ALL
-
-      all_conflicts.select do |conflict|
-        fact_a = find_fact(conflict[:fact_a_id])
-        fact_b = find_fact(conflict[:fact_b_id])
-
-        fact_matches_scope?(fact_a, scope) || fact_matches_scope?(fact_b, scope)
-      end
-    end
-
-    def fact_matches_scope?(fact, scope)
-      Core::ScopeFilter.matches?(fact, scope, @project_path)
-    end
-
-    def apply_scope_filter(dataset, scope)
-      Core::ScopeFilter.apply_to_dataset(dataset, scope, @project_path)
-    end
-
-    def sort_by_scope_priority(facts_with_provenance)
-      Core::FactRanker.sort_by_scope_priority(facts_with_provenance, @project_path)
-    end
-
-    def find_provenance_by_content(content_id)
-      Core::FactQueryBuilder.find_provenance_by_content(@legacy_store, content_id)
-    end
-
-    def find_fact(fact_id)
-      find_fact_from_store(@legacy_store, fact_id)
-    end
-
-    def find_receipts(fact_id)
-      find_receipts_from_store(@legacy_store, fact_id)
-    end
-
-    # Context-aware query helpers
-
-    def facts_by_context_dual(column, value, limit:, scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        facts_by_context_single(store, column, value, limit: limit, source: source)
-      end
-      dedupe_and_sort(results, limit)
-    end
-
-    def facts_by_context_legacy(column, value, limit:, scope:)
-      facts_by_context_single(@legacy_store, column, value, limit: limit, source: :legacy)
-    end
-
-    def facts_by_context_single(store, column, value, limit:, source:)
-      # Find content items matching the context
-      content_ids = store.content_items
-        .where(column => value)
-        .select(:id)
-        .map { |row| row[:id] }
-
-      return [] if content_ids.empty?
-
-      # Find facts linked to those content items via provenance
-      fact_ids = store.provenance
-        .where(content_item_id: content_ids)
-        .select(:fact_id)
-        .distinct
-        .map { |row| row[:fact_id] }
-
-      return [] if fact_ids.empty?
-
-      # Batch fetch facts and their provenance
-      facts_by_id = batch_find_facts(store, fact_ids)
-      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
-
-      results = Core::ResultBuilder.build_results(
-        fact_ids,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      )
-      results.take(limit)
-    end
-
-    def facts_by_tool_dual(tool_name, limit:, scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        facts_by_tool_single(store, tool_name, limit: limit, source: source)
-      end
-      dedupe_and_sort(results, limit)
-    end
-
-    def facts_by_tool_legacy(tool_name, limit:, scope:)
-      facts_by_tool_single(@legacy_store, tool_name, limit: limit, source: :legacy)
-    end
-
-    def facts_by_tool_single(store, tool_name, limit:, source:)
-      # Find content items where the tool was used
-      content_ids = store.tool_calls
-        .where(tool_name: tool_name)
-        .select(:content_item_id)
-        .distinct
-        .map { |row| row[:content_item_id] }
-
-      return [] if content_ids.empty?
-
-      # Find facts linked to those content items via provenance
-      fact_ids = store.provenance
-        .where(content_item_id: content_ids)
-        .select(:fact_id)
-        .distinct
-        .map { |row| row[:fact_id] }
-
-      return [] if fact_ids.empty?
-
-      # Batch fetch facts and their provenance
-      facts_by_id = batch_find_facts(store, fact_ids)
-      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
-
-      results = Core::ResultBuilder.build_results(
-        fact_ids,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      )
-      results.take(limit)
-    end
-
-    # Semantic search helpers
-
-    def query_semantic_dual(text, limit:, scope:, mode:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        query_semantic_single(store, text, limit: limit * 3, mode: mode, source: source)
-      end
-      # Use similarity-preserving dedupe (not source/time sort) to keep RRF ordering
-      Core::FactRanker.dedupe_by_fact_id(results, limit)
-    end
-
-    def query_semantic_legacy(text, limit:, scope:, mode:)
-      query_semantic_single(@legacy_store, text, limit: limit, mode: mode, source: :legacy)
-    end
-
-    def query_semantic_single(store, text, limit:, mode:, source:)
-      vector_results = []
-      text_results = []
-
-      # Text search mode (FTS) - run first for expansion detection
-      if mode == :text || mode == :both
-        text_results = search_by_fts(store, text, limit, source)
-      end
-
-      # Vector search mode - skip if FTS already found strong match
-      if mode == :vector || mode == :both
-        skip_vector = mode == :both && strong_fts_signal?(store, text)
-        vector_results = search_by_vector(store, text, limit, source) unless skip_vector
-      end
-
-      # Merge and deduplicate
-      merge_search_results(vector_results, text_results, limit)
-    end
-
-    def search_by_vector(store, query_text, limit, source)
-      # Generate query embedding
-      query_embedding = @embedding_generator.generate(query_text)
-
-      # Fast path: use sqlite-vec KNN when available
-      vec_index = store.vector_index
-      if vec_index.available?
-        return search_by_vector_native(store, vec_index, query_embedding, limit, source)
-      end
-
-      # Fallback: JSON + Ruby cosine similarity
-      search_by_vector_fallback(store, query_embedding, limit, source)
-    end
-
-    def search_by_vector_native(store, vec_index, query_embedding, limit, source)
-      matches = vec_index.search(query_embedding, k: limit)
-      return [] if matches.empty?
-
-      fact_ids = matches.map { |m| m[:fact_id] }
-      facts_by_id = batch_find_facts(store, fact_ids)
-      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
-
-      Core::ResultBuilder.build_results_with_scores(
-        matches,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      )
-    end
-
-    def search_by_vector_fallback(store, query_embedding, limit, source)
-      # Load facts with embeddings
-      facts_data = store.facts_with_embeddings(limit: 5000)
-      return [] if facts_data.empty?
-
-      # Deduplicate: group facts by embedding, score unique embeddings only, fan out
-      unique_candidates, fact_groups = dedup_candidates(facts_data)
-      return [] if unique_candidates.empty?
-
-      # Calculate similarities on unique embeddings only
-      top_unique = Embeddings::Similarity.top_k(query_embedding, unique_candidates, limit)
-
-      # Fan out: expand unique matches back to all fact_ids sharing that embedding
-      top_matches = fan_out_matches(top_unique, fact_groups, limit)
-
-      # Batch fetch full fact details
-      fact_ids = top_matches.map { |m| m[:candidate][:fact_id] }
-      facts_by_id = batch_find_facts(store, fact_ids)
-      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
-
-      # Build results with similarity scores
-      Core::ResultBuilder.build_results_with_scores(
-        top_matches,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      )
-    end
-
-    # Group facts by embedding_json, return unique candidates + mapping
-    def dedup_candidates(facts_data)
-      groups = {}   # embedding_json → [fact_ids]
-      unique = {}   # embedding_json → parsed candidate (first occurrence)
-
-      facts_data.each do |row|
-        key = row[:embedding_json]
-        if unique.key?(key)
-          groups[key] << row[:id]
-        else
-          candidate = Core::EmbeddingCandidateBuilder.parse_candidate(row)
-          next unless candidate
-          unique[key] = candidate
-          groups[key] = [row[:id]]
-        end
-      end
-
-      [unique.values, groups]
-    end
-
-    # Expand unique matches back to all fact_ids sharing the same embedding
-    def fan_out_matches(top_unique, fact_groups, limit)
-      results = []
-      top_unique.each do |match|
-        candidate = match[:candidate]
-        similarity = match[:similarity]
-
-        # Find the group key for this candidate's embedding
-        group_key = fact_groups.find { |_key, ids| ids.include?(candidate[:fact_id]) }&.first
-        next unless group_key
-
-        fact_groups[group_key].each do |fact_id|
-          results << {
-            candidate: candidate.merge(fact_id: fact_id),
-            similarity: similarity
-          }
-          break if results.size >= limit
-        end
-        break if results.size >= limit
-      end
-
-      results
-    end
-
-    def search_by_fts(store, query_text, limit, source)
-      fts = Index::LexicalFTS.new(store)
-      ranked_results = fts.search_with_ranks(query_text, limit: limit * 2)
-
-      return [] if ranked_results.empty?
-
-      content_ids = ranked_results.map { |r| r[:content_item_id] }
-
-      # Map content_item_ids to fact_ids, preserving FTS rank order
-      provenance_rows = store.provenance
-        .where(content_item_id: content_ids)
-        .select(:fact_id, :content_item_id)
-        .all
-
-      content_to_facts = provenance_rows.group_by { |r| r[:content_item_id] }
-
-      # Build ordered fact list with normalized BM25 scores
-      # FTS5 rank values are negative (more negative = better match)
-      ranks = ranked_results.map { |r| r[:rank] }
-      min_rank = ranks.min # Most negative = best
-      max_rank = ranks.max # Least negative = worst
-      range = (max_rank - min_rank).abs
-
-      seen_fact_ids = Set.new
-      scored_matches = []
-
-      ranked_results.each do |r|
-        similarity = if range > 0
-          # Normalize: best rank → 1.0, worst rank → 0.1
-          0.1 + 0.9 * ((max_rank - r[:rank]).abs / range)
-        else
-          0.8 # Single result gets a reasonable score
-        end
-
-        fact_ids = content_to_facts[r[:content_item_id]]&.map { |p| p[:fact_id] } || []
-        fact_ids.each do |fid|
-          next if seen_fact_ids.include?(fid)
-          seen_fact_ids.add(fid)
-          scored_matches << {fact_id: fid, similarity: similarity}
-        end
-      end
-
-      return [] if scored_matches.empty?
-
-      fact_ids = scored_matches.map { |m| m[:fact_id] }
-      facts_by_id = batch_find_facts(store, fact_ids)
-      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
-
-      Core::ResultBuilder.build_results_with_scores(
-        scored_matches,
-        facts_by_id: facts_by_id,
-        receipts_by_fact_id: receipts_by_fact_id,
-        source: source
-      ).take(limit)
-    end
-
-    def merge_search_results(vector_results, text_results, limit)
-      Core::FactRanker.merge_search_results(vector_results, text_results, limit)
-    end
-
-    def strong_fts_signal?(store, query_text)
-      fts = Index::LexicalFTS.new(store)
-      ranked_results = fts.search_with_ranks(query_text, limit: 5)
-      Recall::ExpansionDetector.strong_fts_signal?(ranked_results)
-    end
-
-    # Multi-concept search helpers
-
-    def query_concepts_dual(concepts, limit:, scope:)
-      template = Recall::DualQueryTemplate.new(@manager)
-      results = template.execute(scope: scope, limit: limit) do |store, source|
-        query_concepts_single(store, concepts, limit: limit * 2, source: source)
-      end
-      # Deduplicate and sort by average similarity
-      dedupe_by_fact_id(results, limit)
-    end
-
-    def query_concepts_legacy(concepts, limit:, scope:)
-      query_concepts_single(@legacy_store, concepts, limit: limit, source: :legacy)
-    end
-
-    def query_concepts_single(store, concepts, limit:, source:)
-      # I/O: Search each concept independently with higher limit for intersection
-      concept_results = concepts.map do |concept|
-        search_by_vector(store, concept, limit * 5, source)
-      end
-
-      # Pure logic: Rank by average similarity across all concepts
-      Core::ConceptRanker.rank_by_concepts(concept_results, limit)
-    end
-
-    def dedupe_by_fact_id(results, limit)
-      Core::FactRanker.dedupe_by_fact_id(results, limit)
+      @engine.query_concepts(concepts, limit: limit, scope: scope)
     end
   end
 end