claude_memory 0.1.0

data/lib/claude_memory/recall.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  class Recall
+    SCOPE_PROJECT = "project"
+    SCOPE_GLOBAL = "global"
+    SCOPE_ALL = "all"
+
+    def initialize(store_or_manager, fts: nil, project_path: nil, env: ENV)
+      @project_path = project_path || env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+
+      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)
+      if @legacy_mode
+        query_legacy(query_text, limit: limit, scope: scope)
+      else
+        query_dual(query_text, limit: limit, scope: scope)
+      end
+    end
+
+    def explain(fact_id, scope: nil)
+      if @legacy_mode
+        explain_from_store(@legacy_store, fact_id)
+      else
+        scope ||= SCOPE_PROJECT
+        store = @manager.store_for_scope(scope)
+        explain_from_store(store, fact_id)
+      end
+    end
+
+    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
+    end
+
+    def conflicts(scope: SCOPE_ALL)
+      if @legacy_mode
+        conflicts_legacy(scope: scope)
+      else
+        conflicts_dual(scope: scope)
+      end
+    end
+
+    private
+
+    def query_dual(query_text, limit:, scope:)
+      results = []
+
+      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
+      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
+      end
+
+      dedupe_and_sort(results, limit)
+    end
+
+    def query_single_store(store, query_text, limit:, source:)
+      fts = Index::LexicalFTS.new(store)
+      content_ids = fts.search(query_text, limit: limit * 3)
+      return [] if content_ids.empty?
+
+      facts_with_provenance = []
+      seen_fact_ids = Set.new
+
+      content_ids.each do |content_id|
+        provenance_records = store.provenance
+          .select(:id, :fact_id, :content_item_id, :quote, :strength)
+          .where(content_item_id: content_id)
+          .all
+
+        provenance_records.each do |prov|
+          next if seen_fact_ids.include?(prov[:fact_id])
+
+          fact = find_fact_from_store(store, prov[:fact_id])
+          next unless fact
+
+          seen_fact_ids.add(prov[:fact_id])
+          facts_with_provenance << {
+            fact: fact,
+            receipts: find_receipts_from_store(store, prov[:fact_id]),
+            source: source
+          }
+          break if facts_with_provenance.size >= limit
+        end
+        break if facts_with_provenance.size >= limit
+      end
+
+      facts_with_provenance
+    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)
+    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
+      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)
+    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
+    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
+      end
+
+      results
+    end
+
+    def explain_from_store(store, fact_id)
+      fact = find_fact_from_store(store, fact_id)
+      return nil 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)
+      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
+    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
+    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)
+    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)
+    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
+    end
+
+    def query_legacy(query_text, limit:, scope:)
+      content_ids = @legacy_fts.search(query_text, limit: limit * 3)
+      return [] if content_ids.empty?
+
+      facts_with_provenance = []
+      seen_fact_ids = Set.new
+
+      content_ids.each do |content_id|
+        provenance_records = find_provenance_by_content(content_id)
+        provenance_records.each do |prov|
+          next if seen_fact_ids.include?(prov[:fact_id])
+
+          fact = find_fact(prov[:fact_id])
+          next unless fact
+          next unless fact_matches_scope?(fact, scope)
+
+          seen_fact_ids.add(prov[:fact_id])
+          facts_with_provenance << {
+            fact: fact,
+            receipts: find_receipts(prov[:fact_id])
+          }
+          break if facts_with_provenance.size >= limit
+        end
+        break if facts_with_provenance.size >= limit
+      end
+
+      sort_by_scope_priority(facts_with_provenance)
+    end
+
+    def changes_legacy(since:, limit:, scope:)
+      ds = @legacy_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)
+
+      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)
+      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
+
+    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
+    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
+    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
+    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
+  end
+end

data/lib/claude_memory/resolve/predicate_policy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Resolve
+    class PredicatePolicy
+      POLICIES = {
+        "convention" => {cardinality: :multi, exclusive: false},
+        "decision" => {cardinality: :multi, exclusive: false},
+        "auth_method" => {cardinality: :single, exclusive: true},
+        "uses_database" => {cardinality: :single, exclusive: true},
+        "uses_framework" => {cardinality: :single, exclusive: true},
+        "deployment_platform" => {cardinality: :single, exclusive: true}
+      }.freeze
+
+      DEFAULT_POLICY = {cardinality: :multi, exclusive: false}.freeze
+
+      def self.policy_for(predicate)
+        POLICIES.fetch(predicate, DEFAULT_POLICY)
+      end
+
+      def self.single?(predicate)
+        policy_for(predicate)[:cardinality] == :single
+      end
+
+      def self.exclusive?(predicate)
+        policy_for(predicate)[:exclusive]
+      end
+    end
+  end
+end

data/lib/claude_memory/resolve/resolver.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Resolve
+    class Resolver
+      def initialize(store)
+        @store = store
+      end
+
+      def apply(extraction, content_item_id: nil, occurred_at: nil, project_path: nil, scope: "project")
+        occurred_at ||= Time.now.utc.iso8601
+        @current_project_path = project_path
+        @current_scope = scope
+
+        result = {
+          entities_created: 0,
+          facts_created: 0,
+          facts_superseded: 0,
+          conflicts_created: 0,
+          provenance_created: 0
+        }
+
+        entity_ids = resolve_entities(extraction.entities)
+        result[:entities_created] = entity_ids.size
+
+        extraction.facts.each do |fact_data|
+          outcome = resolve_fact(fact_data, entity_ids, content_item_id, occurred_at)
+          result[:facts_created] += outcome[:created]
+          result[:facts_superseded] += outcome[:superseded]
+          result[:conflicts_created] += outcome[:conflicts]
+          result[:provenance_created] += outcome[:provenance]
+        end
+
+        result
+      end
+
+      private
+
+      def resolve_entities(entities)
+        entity_ids = {}
+        entities.uniq { |e| [e[:type], e[:name]] }.each do |e|
+          id = @store.find_or_create_entity(type: e[:type], name: e[:name])
+          entity_ids[e[:name]] = id
+        end
+        entity_ids
+      end
+
+      def resolve_fact(fact_data, entity_ids, content_item_id, occurred_at)
+        subject_id = entity_ids[fact_data[:subject]] ||
+          @store.find_or_create_entity(type: "repo", name: fact_data[:subject])
+
+        predicate = fact_data[:predicate]
+        object_val = fact_data[:object]
+        object_entity_id = entity_ids[object_val]
+
+        outcome = {created: 0, superseded: 0, conflicts: 0, provenance: 0}
+
+        existing_facts = @store.facts_for_slot(subject_id, predicate)
+
+        if PredicatePolicy.single?(predicate) && existing_facts.any?
+          matching = existing_facts.find { |f| values_match?(f, object_val, object_entity_id) }
+          if matching
+            add_provenance(matching[:id], content_item_id, fact_data)
+            outcome[:provenance] = 1
+            return outcome
+          elsif supersession_signal?(fact_data)
+            supersede_facts(existing_facts, occurred_at)
+            outcome[:superseded] = existing_facts.size
+          else
+            create_conflict(existing_facts.first[:id], fact_data, subject_id, content_item_id, occurred_at)
+            outcome[:conflicts] = 1
+            return outcome
+          end
+        end
+
+        fact_scope = fact_data[:scope_hint] || @current_scope
+        fact_project = (fact_scope == "global") ? nil : @current_project_path
+
+        fact_id = @store.insert_fact(
+          subject_entity_id: subject_id,
+          predicate: predicate,
+          object_entity_id: object_entity_id,
+          object_literal: object_val,
+          polarity: fact_data[:polarity] || "positive",
+          confidence: fact_data[:confidence] || 1.0,
+          valid_from: occurred_at,
+          scope: fact_scope,
+          project_path: fact_project
+        )
+        outcome[:created] = 1
+
+        if existing_facts.any? && outcome[:superseded] > 0
+          existing_facts.each do |old_fact|
+            @store.insert_fact_link(from_fact_id: fact_id, to_fact_id: old_fact[:id], link_type: "supersedes")
+          end
+        end
+
+        add_provenance(fact_id, content_item_id, fact_data)
+        outcome[:provenance] = 1
+
+        outcome
+      end
+
+      def supersession_signal?(fact_data)
+        (fact_data[:strength] == "stated") ||
+          fact_data.fetch(:supersedes, false)
+      end
+
+      def values_match?(existing_fact, object_val, object_entity_id)
+        existing_fact[:object_literal]&.downcase == object_val&.downcase ||
+          (object_entity_id && existing_fact[:object_entity_id] == object_entity_id)
+      end
+
+      def supersede_facts(facts, occurred_at)
+        facts.each do |fact|
+          @store.update_fact(fact[:id], status: "superseded", valid_to: occurred_at)
+        end
+      end
+
+      def create_conflict(existing_fact_id, new_fact_data, subject_id, content_item_id, occurred_at)
+        new_fact_id = @store.insert_fact(
+          subject_entity_id: subject_id,
+          predicate: new_fact_data[:predicate],
+          object_literal: new_fact_data[:object],
+          polarity: new_fact_data[:polarity] || "positive",
+          confidence: new_fact_data[:confidence] || 1.0,
+          status: "disputed",
+          valid_from: occurred_at,
+          scope: @current_scope,
+          project_path: @current_project_path
+        )
+
+        @store.insert_conflict(
+          fact_a_id: existing_fact_id,
+          fact_b_id: new_fact_id,
+          notes: "Contradicting #{new_fact_data[:predicate]} claims"
+        )
+
+        add_provenance(new_fact_id, content_item_id, new_fact_data)
+      end
+
+      def add_provenance(fact_id, content_item_id, fact_data)
+        @store.insert_provenance(
+          fact_id: fact_id,
+          content_item_id: content_item_id,
+          quote: fact_data[:quote],
+          strength: fact_data[:strength] || "stated"
+        )
+      end
+    end
+  end
+end