claude_memory 0.2.0 → 0.3.0

data/lib/claude_memory/core/concept_ranker.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure business logic for ranking facts by concept similarity
+    # Follows Functional Core pattern (Gary Bernhardt) - no I/O, just transformations
+    class ConceptRanker
+      # Rank facts by average similarity across multiple concepts
+      # Only returns facts that match ALL concepts
+      # @param concept_results [Array<Array<Hash>>] Array of result arrays, one per concept
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Ranked results with :fact, :receipts, :source, :similarity, :concept_similarities
+      def self.rank_by_concepts(concept_results, limit)
+        fact_map = build_fact_map(concept_results)
+        multi_concept_facts = filter_by_all_concepts(fact_map, concept_results.size)
+        return [] if multi_concept_facts.empty?
+
+        rank_by_average_similarity(multi_concept_facts, limit)
+      end
+
+      # Build a map of fact_id => array of result matches from each concept
+      def self.build_fact_map(concept_results)
+        fact_map = Hash.new { |h, k| h[k] = [] }
+
+        concept_results.each_with_index do |results, concept_idx|
+          results.each do |result|
+            fact_id = result[:fact][:id]
+            fact_map[fact_id] << {
+              result: result,
+              concept_idx: concept_idx,
+              similarity: result[:similarity] || 0.0
+            }
+          end
+        end
+
+        fact_map
+      end
+      private_class_method :build_fact_map
+
+      # Filter to only facts that appear in ALL concept result sets
+      def self.filter_by_all_concepts(fact_map, expected_concept_count)
+        fact_map.select do |_fact_id, matches|
+          represented_concepts = matches.map { |m| m[:concept_idx] }.uniq
+          represented_concepts.size == expected_concept_count
+        end
+      end
+      private_class_method :filter_by_all_concepts
+
+      # Rank multi-concept facts by average similarity score
+      def self.rank_by_average_similarity(multi_concept_facts, limit)
+        ranked = multi_concept_facts.map do |_fact_id, matches|
+          similarities = matches.map { |m| m[:similarity] }
+          avg_similarity = similarities.sum / similarities.size.to_f
+
+          # Use the first match for fact and receipts data
+          first_match = matches.first[:result]
+
+          {
+            fact: first_match[:fact],
+            receipts: first_match[:receipts],
+            source: first_match[:source],
+            similarity: avg_similarity,
+            concept_similarities: similarities
+          }
+        end
+
+        # Sort by average similarity (highest first)
+        ranked.sort_by { |r| -r[:similarity] }.take(limit)
+      end
+      private_class_method :rank_by_average_similarity
+    end
+  end
+end

data/lib/claude_memory/core/embedding_candidate_builder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Core
+    # Pure logic for building embedding candidates from fact data
+    # Follows Functional Core pattern - no I/O, just transformations
+    class EmbeddingCandidateBuilder
+      # Parse embeddings and prepare candidates for similarity calculation
+      # @param facts_data [Array<Hash>] Fact rows with :embedding_json, :id, etc.
+      # @return [Array<Hash>] Candidates with parsed :embedding arrays
+      def self.build_candidates(facts_data)
+        facts_data.map do |row|
+          parse_candidate(row)
+        end.compact
+      end
+
+      # Parse a single fact row into a candidate
+      # @param row [Hash] Fact row with :embedding_json, :id, etc.
+      # @return [Hash, nil] Candidate hash or nil if parse fails
+      def self.parse_candidate(row)
+        embedding = JSON.parse(row[:embedding_json])
+        {
+          fact_id: row[:id],
+          embedding: embedding,
+          subject_entity_id: row[:subject_entity_id],
+          predicate: row[:predicate],
+          object_literal: row[:object_literal],
+          scope: row[:scope]
+        }
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/claude_memory/core/fact_collector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure logic for collecting and ordering fact IDs from provenance records
+    # Follows Functional Core pattern - no I/O, just transformations
+    class FactCollector
+      # Collect fact IDs from provenance records, maintaining content order and deduplicating
+      # @param provenance_by_content [Hash] Map of content_id => array of provenance records with :fact_id
+      # @param content_ids [Array<Integer>] Ordered content IDs
+      # @param limit [Integer] Maximum fact IDs to collect
+      # @return [Array<Integer>] Ordered, deduplicated fact IDs
+      def self.collect_ordered_fact_ids(provenance_by_content, content_ids, limit)
+        return [] if limit <= 0
+
+        seen_fact_ids = Set.new
+        ordered_fact_ids = []
+
+        content_ids.each do |content_id|
+          provenance_records = provenance_by_content[content_id] || []
+
+          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
+
+        ordered_fact_ids
+      end
+
+      # Extract unique fact IDs from array of provenance records
+      # @param provenance_records [Array<Hash>] Records with :fact_id
+      # @return [Array<Integer>] Unique fact IDs
+      def self.extract_fact_ids(provenance_records)
+        provenance_records.map { |p| p[:fact_id] }.uniq
+      end
+
+      # Extract unique content IDs from array of provenance records
+      # @param provenance_records [Array<Hash>] Records with :content_item_id
+      # @return [Array<Integer>] Unique content IDs
+      def self.extract_content_ids(provenance_records)
+        provenance_records.map { |p| p[:content_item_id] }.uniq
+      end
+    end
+  end
+end

data/lib/claude_memory/core/fact_query_builder.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Query construction logic for fact-related database queries
+    # Builds Sequel datasets with appropriate joins and selects
+    # Follows Functional Core pattern - pure query building, no execution
+    class FactQueryBuilder
+      # Build dataset for batch finding facts with entity joins
+      # @param store [SQLiteStore] Database store
+      # @param fact_ids [Array<Integer>] Fact IDs to load
+      # @return [Hash] Hash of fact_id => fact_row
+      def self.batch_find_facts(store, fact_ids)
+        return {} if fact_ids.empty?
+
+        results = build_facts_dataset(store)
+          .where(Sequel[:facts][:id] => fact_ids)
+          .all
+
+        results.each_with_object({}) { |row, hash| hash[row[:id]] = row }
+      end
+
+      # Build dataset for batch finding receipts (provenance) with content_items join
+      # @param store [SQLiteStore] Database store
+      # @param fact_ids [Array<Integer>] Fact IDs to find receipts for
+      # @return [Hash] Hash of fact_id => [receipt_rows]
+      def self.batch_find_receipts(store, fact_ids)
+        return {} if fact_ids.empty?
+
+        results = build_receipts_dataset(store)
+          .where(Sequel[:provenance][:fact_id] => fact_ids)
+          .all
+
+        results.group_by { |row| row[:fact_id] }.tap do |grouped|
+          # Ensure all requested fact_ids have an entry (empty array if no receipts)
+          fact_ids.each { |id| grouped[id] ||= [] }
+        end
+      end
+
+      # Find single fact by ID with entity join
+      # @param store [SQLiteStore] Database store
+      # @param fact_id [Integer] Fact ID
+      # @return [Hash, nil] Fact row or nil
+      def self.find_fact(store, fact_id)
+        build_facts_dataset(store)
+          .where(Sequel[:facts][:id] => fact_id)
+          .first
+      end
+
+      # Find receipts for a single fact
+      # @param store [SQLiteStore] Database store
+      # @param fact_id [Integer] Fact ID
+      # @return [Array<Hash>] Receipt rows
+      def self.find_receipts(store, fact_id)
+        build_receipts_dataset(store)
+          .where(Sequel[:provenance][:fact_id] => fact_id)
+          .all
+      end
+
+      # Find fact IDs that supersede the given fact
+      # @param store [SQLiteStore] Database store
+      # @param fact_id [Integer] Fact ID
+      # @return [Array<Integer>] Fact IDs
+      def self.find_superseded_by(store, fact_id)
+        store.fact_links
+          .where(to_fact_id: fact_id, link_type: "supersedes")
+          .select_map(:from_fact_id)
+      end
+
+      # Find fact IDs that are superseded by the given fact
+      # @param store [SQLiteStore] Database store
+      # @param fact_id [Integer] Fact ID
+      # @return [Array<Integer>] Fact IDs
+      def self.find_supersedes(store, fact_id)
+        store.fact_links
+          .where(from_fact_id: fact_id, link_type: "supersedes")
+          .select_map(:to_fact_id)
+      end
+
+      # Find conflicts involving the given fact
+      # @param store [SQLiteStore] Database store
+      # @param fact_id [Integer] Fact ID
+      # @return [Array<Hash>] Conflict rows
+      def self.find_conflicts(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
+      end
+
+      # Find facts created since a given timestamp
+      # @param store [SQLiteStore] Database store
+      # @param since [Time, String] Timestamp
+      # @param limit [Integer] Maximum results
+      # @return [Array<Hash>] Fact rows
+      def self.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
+      end
+
+      # Find provenance records for a content item
+      # @param store [SQLiteStore] Database store
+      # @param content_id [Integer] Content item ID
+      # @return [Array<Hash>] Provenance rows
+      def self.find_provenance_by_content(store, content_id)
+        store.provenance
+          .select(:id, :fact_id, :content_item_id, :quote, :strength)
+          .where(content_item_id: content_id)
+          .all
+      end
+
+      # Build standard facts dataset with entity join and all necessary columns
+      # @param store [SQLiteStore] Database store
+      # @return [Sequel::Dataset] Configured dataset
+      def self.build_facts_dataset(store)
+        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]
+          )
+      end
+
+      # Build standard receipts dataset with content_items join
+      # @param store [SQLiteStore] Database store
+      # @return [Sequel::Dataset] Configured dataset
+      def self.build_receipts_dataset(store)
+        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]
+          )
+      end
+    end
+  end
+end

data/lib/claude_memory/core/fact_ranker.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure business logic for ranking, sorting, and deduplicating facts
+    # Follows Functional Core pattern (Gary Bernhardt) - no I/O, just transformations
+    class FactRanker
+      # Deduplicate index results by fact signature and sort by source priority
+      # @param results [Array<Hash>] Results with :subject, :predicate, :object_preview, :source
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Deduplicated and sorted results
+      def self.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)
+      end
+
+      # Deduplicate full fact results by signature and sort by source + creation time
+      # @param results [Array<Hash>] Results with :fact hash containing fact data, :source symbol
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Deduplicated and sorted results
+      def self.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)
+      end
+
+      # Sort facts by scope priority: current project > global > other projects
+      # @param facts_with_provenance [Array<Hash>] Facts with :fact hash containing scope and project_path
+      # @param project_path [String] Current project path for comparison
+      # @return [Array<Hash>] Sorted facts
+      def self.sort_by_scope_priority(facts_with_provenance, project_path)
+        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
+      end
+
+      # Deduplicate semantic search results by fact_id, keeping highest similarity
+      # @param results [Array<Hash>] Results with :fact hash containing :id and :similarity score
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Deduplicated results sorted by similarity descending
+      def self.dedupe_by_fact_id(results, limit)
+        seen = {}
+
+        results.each do |result|
+          fact_id = result[:fact][:id]
+          # Keep the result with highest similarity for each fact
+          if !seen[fact_id] || seen[fact_id][:similarity] < result[:similarity]
+            seen[fact_id] = result
+          end
+        end
+
+        seen.values.sort_by { |r| -r[:similarity] }.take(limit)
+      end
+
+      # Merge vector and text search results, preferring vector similarity scores
+      # @param vector_results [Array<Hash>] Results from vector search with :fact and :similarity
+      # @param text_results [Array<Hash>] Results from text search with :fact and :similarity
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Merged results sorted by similarity descending
+      def self.merge_search_results(vector_results, text_results, limit)
+        # Combine results, preferring vector similarity scores
+        combined = {}
+
+        vector_results.each do |result|
+          fact_id = result[:fact][:id]
+          combined[fact_id] = result
+        end
+
+        text_results.each do |result|
+          fact_id = result[:fact][:id]
+          # Only add if not already present from vector search
+          combined[fact_id] ||= result
+        end
+
+        # Sort by similarity score (highest first)
+        combined.values
+          .sort_by { |r| -(r[:similarity] || 0) }
+          .take(limit)
+      end
+    end
+  end
+end

data/lib/claude_memory/core/result_builder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure utility for building fact result hashes from batch-fetched data
+    # Follows Functional Core pattern - no I/O, just transformations
+    class ResultBuilder
+      # Build fact results from batch-fetched facts and receipts
+      # @param fact_ids [Array<Integer>] Fact IDs to build results for
+      # @param facts_by_id [Hash] Map of fact_id => fact_hash
+      # @param receipts_by_fact_id [Hash] Map of fact_id => array of receipts
+      # @param source [Symbol] Source identifier (:project, :global, :legacy)
+      # @param similarity [Float, nil] Optional similarity score
+      # @return [Array<Hash>] Array of result hashes with :fact, :receipts, :source, :similarity
+      def self.build_results(fact_ids, facts_by_id:, receipts_by_fact_id:, source:, similarity: nil)
+        fact_ids.map do |fact_id|
+          fact = facts_by_id[fact_id]
+          next unless fact
+
+          result = {
+            fact: fact,
+            receipts: receipts_by_fact_id[fact_id] || [],
+            source: source
+          }
+          result[:similarity] = similarity if similarity
+          result
+        end.compact
+      end
+
+      # Build results with variable similarity scores
+      # @param matches [Array<Hash>] Array of matches with :fact_id and :similarity
+      # @param facts_by_id [Hash] Map of fact_id => fact_hash
+      # @param receipts_by_fact_id [Hash] Map of fact_id => array of receipts
+      # @param source [Symbol] Source identifier
+      # @return [Array<Hash>] Array of result hashes with varying similarity scores
+      def self.build_results_with_scores(matches, facts_by_id:, receipts_by_fact_id:, source:)
+        matches.map do |match|
+          fact_id = match[:fact_id] || match[:candidate]&.[](:fact_id)
+          next unless fact_id
+
+          fact = facts_by_id[fact_id]
+          next unless fact
+
+          {
+            fact: fact,
+            receipts: receipts_by_fact_id[fact_id] || [],
+            source: source,
+            similarity: match[:similarity]
+          }
+        end.compact
+      end
+    end
+  end
+end

data/lib/claude_memory/core/result_sorter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure logic for sorting and limiting result collections
+    # Follows Functional Core pattern - no I/O, just transformations
+    class ResultSorter
+      # Sort results by timestamp (created_at) in descending order and apply limit
+      # @param results [Array<Hash>] Results with :created_at keys
+      # @param limit [Integer] Maximum results to return
+      # @return [Array<Hash>] Sorted, limited results (most recent first)
+      def self.sort_by_timestamp(results, limit)
+        results.sort_by { |r| r[:created_at] }.reverse.first(limit)
+      end
+
+      # Add source annotation to each result in collection
+      # @param results [Array<Hash>] Results to annotate
+      # @param source [Symbol] Source identifier (:project, :global, :legacy)
+      # @return [Array<Hash>] Results with :source key added (mutates in place)
+      def self.annotate_source(results, source)
+        results.each { |r| r[:source] = source }
+      end
+    end
+  end
+end

data/lib/claude_memory/core/scope_filter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure business logic for scope filtering and matching
+    # Follows Functional Core pattern - no I/O, just transformations
+    class ScopeFilter
+      SCOPE_ALL = "all"
+      SCOPE_PROJECT = "project"
+      SCOPE_GLOBAL = "global"
+
+      # Check if a fact matches the given scope
+      # @param fact [Hash] Fact record with :scope and :project_path
+      # @param scope [String] Scope to match against ("all", "project", "global")
+      # @param project_path [String] Current project path for project scope matching
+      # @return [Boolean] True if fact matches scope
+      def self.matches?(fact, scope, project_path)
+        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
+      end
+
+      # Apply scope filter to a Sequel dataset
+      # @param dataset [Sequel::Dataset] Dataset to filter
+      # @param scope [String] Scope to filter by
+      # @param project_path [String] Current project path for project scope
+      # @return [Sequel::Dataset] Filtered dataset
+      def self.apply_to_dataset(dataset, scope, project_path)
+        case scope
+        when SCOPE_PROJECT
+          dataset.where(scope: "project", project_path: project_path)
+        when SCOPE_GLOBAL
+          dataset.where(scope: "global")
+        else
+          dataset
+        end
+      end
+
+      # Filter array of facts by scope
+      # @param facts [Array<Hash>] Facts to filter
+      # @param scope [String] Scope to filter by
+      # @param project_path [String] Current project path
+      # @return [Array<Hash>] Filtered facts
+      def self.filter_facts(facts, scope, project_path)
+        return facts if scope == SCOPE_ALL
+
+        facts.select { |fact| matches?(fact, scope, project_path) }
+      end
+    end
+  end
+end

data/lib/claude_memory/core/text_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Pure logic for building searchable text from structured data
+    # Follows Functional Core pattern - no I/O, just transformations
+    class TextBuilder
+      # Build searchable text from entities, facts, and decisions
+      # @param entities [Array<Hash>] Entities with :type and :name
+      # @param facts [Array<Hash>] Facts with :subject, :predicate, :object, :quote
+      # @param decisions [Array<Hash>] Decisions with :title and :summary
+      # @return [String] Concatenated searchable text
+      def self.build_searchable_text(entities, facts, decisions)
+        parts = []
+        entities.each { |e| parts << "#{e[:type]}: #{e[:name]}" }
+        facts.each { |f| parts << "#{f[:subject]} #{f[:predicate]} #{f[:object]} #{f[:quote]}" }
+        decisions.each { |d| parts << "#{d[:title]} #{d[:summary]}" }
+        parts.join(" ").strip
+      end
+
+      # Transform hash keys from strings to symbols
+      # @param hash [Hash] Hash with string or symbol keys
+      # @return [Hash] Hash with symbolized keys
+      def self.symbolize_keys(hash)
+        hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end