claude_memory 0.2.0 → 0.3.0

data/lib/claude_memory/recall.rb

@@ -24,8 +24,10 @@ module ClaudeMemory
       end
     end
 
-    def initialize(store_or_manager, fts: nil, project_path: nil, env: ENV)
-      @project_path = project_path || env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+    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
@@ -79,49 +81,63 @@ module ClaudeMemory
       end
     end
 
-    private
-
-    def query_dual(query_text, limit:, scope:)
-      results = []
+    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
+    end
 
-      if scope == SCOPE_ALL || scope == SCOPE_PROJECT
-        @manager.ensure_project! if @manager.project_exists?
-        if @manager.project_store
-          project_results = query_single_store(@manager.project_store, query_text, limit: limit, source: :project)
-          results.concat(project_results)
-        end
+    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
+    end
 
-      if scope == SCOPE_ALL || scope == SCOPE_GLOBAL
-        @manager.ensure_global! if @manager.global_exists?
-        if @manager.global_store
-          global_results = query_single_store(@manager.global_store, query_text, limit: limit, source: :global)
-          results.concat(global_results)
-        end
+    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
 
-      dedupe_and_sort(results, limit)
+    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
 
-    def query_index_dual(query_text, limit:, scope:)
-      results = []
+    def query_concepts(concepts, limit: 10, scope: SCOPE_ALL)
+      raise ArgumentError, "Must provide 2-5 concepts" unless (2..5).cover?(concepts.size)
 
-      if scope == SCOPE_ALL || scope == SCOPE_PROJECT
-        @manager.ensure_project! if @manager.project_exists?
-        if @manager.project_store
-          project_results = query_index_single_store(@manager.project_store, query_text, limit: limit, source: :project)
-          results.concat(project_results)
-        end
+      if @legacy_mode
+        query_concepts_legacy(concepts, limit: limit, scope: scope)
+      else
+        query_concepts_dual(concepts, limit: limit, scope: scope)
       end
+    end
 
-      if scope == SCOPE_ALL || scope == SCOPE_GLOBAL
-        @manager.ensure_global! if @manager.global_exists?
-        if @manager.global_store
-          global_results = query_index_single_store(@manager.global_store, query_text, limit: limit, source: :global)
-          results.concat(global_results)
-        end
+    private
+
+    def query_dual(query_text, limit:, scope:)
+      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)
       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
 
@@ -138,22 +154,7 @@ module ClaudeMemory
     end
 
     def dedupe_and_sort_index(results, limit)
-      seen_signatures = Set.new
-      unique_results = []
-
-      results.each do |result|
-        sig = "#{result[:subject]}:#{result[:predicate]}:#{result[:object_preview]}"
-        next if seen_signatures.include?(sig)
-
-        seen_signatures.add(sig)
-        unique_results << result
-      end
-
-      # Sort by source priority (project first)
-      unique_results.sort_by do |item|
-        source_priority = (item[:source] == :project) ? 0 : 1
-        [source_priority]
-      end.first(limit)
+      Core::FactRanker.dedupe_and_sort_index(results, limit)
     end
 
     def query_single_store(store, query_text, limit:, source:)
@@ -161,27 +162,22 @@ module ClaudeMemory
       content_ids = fts.search(query_text, limit: limit * 3)
       return [] if content_ids.empty?
 
-      # Collect all fact_ids first
-      seen_fact_ids = Set.new
-      ordered_fact_ids = []
-
+      # Build provenance map for ordered collection
+      provenance_by_content = {}
       content_ids.each do |content_id|
-        provenance_records = store.provenance
+        provenance_by_content[content_id] = store.provenance
           .select(:fact_id)
           .where(content_item_id: content_id)
           .all
-
-        provenance_records.each do |prov|
-          fact_id = prov[:fact_id]
-          next if seen_fact_ids.include?(fact_id)
-
-          seen_fact_ids.add(fact_id)
-          ordered_fact_ids << fact_id
-          break if ordered_fact_ids.size >= limit
-        end
-        break if ordered_fact_ids.size >= limit
       end
 
+      # 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
@@ -191,129 +187,47 @@ module ClaudeMemory
       receipts_by_fact_id = batch_find_receipts(store, ordered_fact_ids)
 
       # Build results maintaining order
-      ordered_fact_ids.map do |fact_id|
-        fact = facts_by_id[fact_id]
-        next unless fact
-
-        {
-          fact: fact,
-          receipts: receipts_by_fact_id[fact_id] || [],
-          source: source
-        }
-      end.compact
+      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)
-      store.facts
-        .left_join(:entities, id: :subject_entity_id)
-        .select(
-          Sequel[:facts][:id],
-          Sequel[:facts][:predicate],
-          Sequel[:facts][:object_literal],
-          Sequel[:facts][:status],
-          Sequel[:facts][:confidence],
-          Sequel[:facts][:valid_from],
-          Sequel[:facts][:valid_to],
-          Sequel[:facts][:created_at],
-          Sequel[:entities][:canonical_name].as(:subject_name),
-          Sequel[:facts][:scope],
-          Sequel[:facts][:project_path]
-        )
-        .where(Sequel[:facts][:id] => fact_ids)
-        .all
-        .each_with_object({}) { |fact, hash| hash[fact[:id]] = fact }
+      Core::FactQueryBuilder.batch_find_facts(store, fact_ids)
     end
 
     def batch_find_receipts(store, fact_ids)
-      store.provenance
-        .left_join(:content_items, id: :content_item_id)
-        .select(
-          Sequel[:provenance][:id],
-          Sequel[:provenance][:fact_id],
-          Sequel[:provenance][:quote],
-          Sequel[:provenance][:strength],
-          Sequel[:content_items][:session_id],
-          Sequel[:content_items][:occurred_at]
-        )
-        .where(Sequel[:provenance][:fact_id] => fact_ids)
-        .all
-        .group_by { |receipt| receipt[:fact_id] }
+      Core::FactQueryBuilder.batch_find_receipts(store, fact_ids)
     end
 
     def dedupe_and_sort(results, limit)
-      seen_signatures = Set.new
-      unique_results = []
-
-      results.each do |result|
-        fact = result[:fact]
-        sig = "#{fact[:subject_name]}:#{fact[:predicate]}:#{fact[:object_literal]}"
-        next if seen_signatures.include?(sig)
-
-        seen_signatures.add(sig)
-        unique_results << result
-      end
-
-      unique_results.sort_by do |item|
-        source_priority = (item[:source] == :project) ? 0 : 1
-        [source_priority, item[:fact][:created_at]]
-      end.first(limit)
+      Core::FactRanker.dedupe_and_sort(results, limit)
     end
 
     def changes_dual(since:, limit:, scope:)
-      results = []
-
-      if scope == SCOPE_ALL || scope == SCOPE_PROJECT
-        @manager.ensure_project! if @manager.project_exists?
-        if @manager.project_store
-          project_changes = fetch_changes(@manager.project_store, since, limit)
-          project_changes.each { |c| c[:source] = :project }
-          results.concat(project_changes)
-        end
+      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)
+        changes
       end
-
-      if scope == SCOPE_ALL || scope == SCOPE_GLOBAL
-        @manager.ensure_global! if @manager.global_exists?
-        if @manager.global_store
-          global_changes = fetch_changes(@manager.global_store, since, limit)
-          global_changes.each { |c| c[:source] = :global }
-          results.concat(global_changes)
-        end
-      end
-
-      results.sort_by { |c| c[:created_at] }.reverse.first(limit)
+      Core::ResultSorter.sort_by_timestamp(results, limit)
     end
 
     def fetch_changes(store, since, limit)
-      store.facts
-        .select(:id, :subject_entity_id, :predicate, :object_literal, :status, :created_at, :scope, :project_path)
-        .where { created_at >= since }
-        .order(Sequel.desc(:created_at))
-        .limit(limit)
-        .all
+      Core::FactQueryBuilder.fetch_changes(store, since, limit)
     end
 
     def conflicts_dual(scope:)
-      results = []
-
-      if scope == SCOPE_ALL || scope == SCOPE_PROJECT
-        @manager.ensure_project! if @manager.project_exists?
-        if @manager.project_store
-          project_conflicts = @manager.project_store.open_conflicts
-          project_conflicts.each { |c| c[:source] = :project }
-          results.concat(project_conflicts)
-        end
-      end
-
-      if scope == SCOPE_ALL || scope == SCOPE_GLOBAL
-        @manager.ensure_global! if @manager.global_exists?
-        if @manager.global_store
-          global_conflicts = @manager.global_store.open_conflicts
-          global_conflicts.each { |c| c[:source] = :global }
-          results.concat(global_conflicts)
-        end
+      template = Recall::DualQueryTemplate.new(@manager)
+      template.execute(scope: scope) do |store, source|
+        conflicts = store.open_conflicts
+        Core::ResultSorter.annotate_source(conflicts, source)
+        conflicts
       end
-
-      results
     end
 
     def explain_from_store(store, fact_id)
@@ -330,56 +244,23 @@ module ClaudeMemory
     end
 
     def find_fact_from_store(store, fact_id)
-      store.facts
-        .left_join(:entities, id: :subject_entity_id)
-        .select(
-          Sequel[:facts][:id],
-          Sequel[:facts][:predicate],
-          Sequel[:facts][:object_literal],
-          Sequel[:facts][:status],
-          Sequel[:facts][:confidence],
-          Sequel[:facts][:valid_from],
-          Sequel[:facts][:valid_to],
-          Sequel[:facts][:created_at],
-          Sequel[:entities][:canonical_name].as(:subject_name),
-          Sequel[:facts][:scope],
-          Sequel[:facts][:project_path]
-        )
-        .where(Sequel[:facts][:id] => fact_id)
-        .first
+      Core::FactQueryBuilder.find_fact(store, fact_id)
     end
 
     def find_receipts_from_store(store, fact_id)
-      store.provenance
-        .left_join(:content_items, id: :content_item_id)
-        .select(
-          Sequel[:provenance][:id],
-          Sequel[:provenance][:quote],
-          Sequel[:provenance][:strength],
-          Sequel[:content_items][:session_id],
-          Sequel[:content_items][:occurred_at]
-        )
-        .where(Sequel[:provenance][:fact_id] => fact_id)
-        .all
+      Core::FactQueryBuilder.find_receipts(store, fact_id)
     end
 
     def find_superseded_by_from_store(store, fact_id)
-      store.fact_links
-        .where(to_fact_id: fact_id, link_type: "supersedes")
-        .select_map(:from_fact_id)
+      Core::FactQueryBuilder.find_superseded_by(store, fact_id)
     end
 
     def find_supersedes_from_store(store, fact_id)
-      store.fact_links
-        .where(from_fact_id: fact_id, link_type: "supersedes")
-        .select_map(:to_fact_id)
+      Core::FactQueryBuilder.find_supersedes(store, fact_id)
     end
 
     def find_conflicts_from_store(store, fact_id)
-      store.conflicts
-        .select(:id, :fact_a_id, :fact_b_id, :status)
-        .where(Sequel.or(fact_a_id: fact_id, fact_b_id: fact_id))
-        .all
+      Core::FactQueryBuilder.find_conflicts(store, fact_id)
     end
 
     def query_legacy(query_text, limit:, scope:)
@@ -454,47 +335,19 @@ module ClaudeMemory
     end
 
     def fact_matches_scope?(fact, scope)
-      return true if scope == SCOPE_ALL
-
-      fact_scope = fact[:scope] || "project"
-      fact_project = fact[:project_path]
-
-      case scope
-      when SCOPE_PROJECT
-        fact_scope == "project" && fact_project == @project_path
-      when SCOPE_GLOBAL
-        fact_scope == "global"
-      else
-        true
-      end
+      Core::ScopeFilter.matches?(fact, scope, @project_path)
     end
 
     def apply_scope_filter(dataset, scope)
-      case scope
-      when SCOPE_PROJECT
-        dataset.where(scope: "project", project_path: @project_path)
-      when SCOPE_GLOBAL
-        dataset.where(scope: "global")
-      else
-        dataset
-      end
+      Core::ScopeFilter.apply_to_dataset(dataset, scope, @project_path)
     end
 
     def sort_by_scope_priority(facts_with_provenance)
-      facts_with_provenance.sort_by do |item|
-        fact = item[:fact]
-        is_current_project = fact[:project_path] == @project_path
-        is_global = fact[:scope] == "global"
-
-        [is_current_project ? 0 : 1, is_global ? 0 : 1]
-      end
+      Core::FactRanker.sort_by_scope_priority(facts_with_provenance, @project_path)
     end
 
     def find_provenance_by_content(content_id)
-      @legacy_store.provenance
-        .select(:id, :fact_id, :content_item_id, :quote, :strength)
-        .where(content_item_id: content_id)
-        .all
+      Core::FactQueryBuilder.find_provenance_by_content(@legacy_store, content_id)
     end
 
     def find_fact(fact_id)
@@ -504,5 +357,219 @@ module ClaudeMemory
     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
+      dedupe_and_sort(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 = []
+
+      # Vector search mode
+      if mode == :vector || mode == :both
+        vector_results = search_by_vector(store, text, limit, source)
+      end
+
+      # Text search mode (FTS)
+      if mode == :text || mode == :both
+        text_results = search_by_fts(store, text, limit, source)
+      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)
+
+      # Load facts with embeddings
+      facts_data = store.facts_with_embeddings(limit: 5000)
+      return [] if facts_data.empty?
+
+      # Parse embeddings and prepare candidates
+      candidates = Core::EmbeddingCandidateBuilder.build_candidates(facts_data)
+
+      return [] if candidates.empty?
+
+      # Calculate similarities and rank
+      top_matches = Embeddings::Similarity.top_k(query_embedding, candidates, 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
+
+    def search_by_fts(store, query_text, limit, source)
+      # Use existing FTS search infrastructure
+      fts = Index::LexicalFTS.new(store)
+      content_ids = fts.search(query_text, limit: limit * 2)
+
+      return [] if content_ids.empty?
+
+      # Find facts from content items
+      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
+      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,
+        similarity: 0.5  # Default score for FTS results
+      )
+      results.take(limit)
+    end
+
+    def merge_search_results(vector_results, text_results, limit)
+      Core::FactRanker.merge_search_results(vector_results, text_results, limit)
+    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)
+    end
   end
 end