claude_memory 0.1.0 → 0.2.0

data/lib/claude_memory/core/result.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Result type for consistent return values across the codebase.
+    # Replaces inconsistent nil/integer/hash returns with explicit Success/Failure types.
+    #
+    # @example Success case
+    #   result = Result.success(42)
+    #   result.success? # => true
+    #   result.value # => 42
+    #
+    # @example Failure case
+    #   result = Result.failure("Something went wrong")
+    #   result.failure? # => true
+    #   result.error # => "Something went wrong"
+    #
+    # @example Chaining operations
+    #   Result.success(5)
+    #     .map { |v| v * 2 }
+    #     .flat_map { |v| Result.success(v + 1) }
+    #     .value # => 11
+    class Result
+      # Creates a successful result
+      # @param value [Object] the success value
+      # @return [Success] a success result
+      def self.success(value = nil)
+        Success.new(value)
+      end
+
+      # Creates a failed result
+      # @param error [String, Exception] the error
+      # @return [Failure] a failure result
+      def self.failure(error)
+        Failure.new(error)
+      end
+
+      # @return [Boolean] true if this is a success result
+      def success?
+        raise NotImplementedError
+      end
+
+      # @return [Boolean] true if this is a failure result
+      def failure?
+        !success?
+      end
+
+      # @return [Object] the success value
+      # @raise [RuntimeError] if called on a failure
+      def value
+        raise NotImplementedError
+      end
+
+      # @return [String, Exception, nil] the error, or nil for success
+      def error
+        raise NotImplementedError
+      end
+
+      # Transforms the value if success, otherwise returns self
+      # @yield [Object] the success value
+      # @return [Result] a new result with the transformed value
+      def map
+        raise NotImplementedError
+      end
+
+      # Chains another result-returning operation if success
+      # @yield [Object] the success value
+      # @return [Result] the result from the block, or self if failure
+      def flat_map
+        raise NotImplementedError
+      end
+
+      # Returns the value if success, otherwise returns the default
+      # @param default [Object] the default value
+      # @return [Object] the value or default
+      def or_else(default)
+        raise NotImplementedError
+      end
+    end
+
+    # Success result type
+    class Success < Result
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      def success?
+        true
+      end
+
+      def error
+        nil
+      end
+
+      def map
+        return self unless block_given?
+        Success.new(yield(value))
+      end
+
+      def flat_map
+        return self unless block_given?
+        yield(value)
+      end
+
+      def or_else(_default)
+        value
+      end
+    end
+
+    # Failure result type
+    class Failure < Result
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+        freeze
+      end
+
+      def success?
+        false
+      end
+
+      def value
+        raise "Cannot get value from Failure: #{error}"
+      end
+
+      def map
+        self
+      end
+
+      def flat_map
+        self
+      end
+
+      def or_else(default)
+        default
+      end
+    end
+  end
+end

data/lib/claude_memory/core/session_id.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Value object representing a session identifier
+    # Provides type safety and validation for session IDs
+    class SessionId
+      attr_reader :value
+
+      def initialize(value)
+        @value = value.to_s
+        validate!
+        freeze
+      end
+
+      def to_s
+        value
+      end
+
+      def ==(other)
+        other.is_a?(SessionId) && other.value == value
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        value.hash
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "Session ID cannot be empty" if value.empty?
+      end
+    end
+  end
+end

data/lib/claude_memory/core/token_estimator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    class TokenEstimator
+      # Approximation: ~4 characters per token for English text
+      # More accurate for Claude's tokenizer than simple word count
+      CHARS_PER_TOKEN = 4.0
+
+      def self.estimate(text)
+        return 0 if text.nil? || text.empty?
+
+        # Remove extra whitespace and count characters
+        normalized = text.strip.gsub(/\s+/, " ")
+        chars = normalized.length
+
+        # Return ceiling to avoid underestimation
+        (chars / CHARS_PER_TOKEN).ceil
+      end
+
+      def self.estimate_fact(fact)
+        # Estimate tokens for a fact record
+        text = [
+          fact[:subject_name],
+          fact[:predicate],
+          fact[:object_literal]
+        ].compact.join(" ")
+
+        estimate(text)
+      end
+    end
+  end
+end

data/lib/claude_memory/core/transcript_path.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Value object representing a transcript file path
+    # Provides type safety and validation for file paths
+    class TranscriptPath
+      attr_reader :value
+
+      def initialize(value)
+        @value = value.to_s
+        validate!
+        freeze
+      end
+
+      def to_s
+        value
+      end
+
+      def ==(other)
+        other.is_a?(TranscriptPath) && other.value == value
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        value.hash
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "Transcript path cannot be empty" if value.empty?
+      end
+    end
+  end
+end

data/lib/claude_memory/domain/conflict.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Domain
+    # Domain model representing a conflict between two facts
+    class Conflict
+      attr_reader :id, :fact_a_id, :fact_b_id, :status, :notes,
+        :detected_at, :resolved_at
+
+      def initialize(attributes)
+        @id = attributes[:id]
+        @fact_a_id = attributes[:fact_a_id]
+        @fact_b_id = attributes[:fact_b_id]
+        @status = attributes[:status] || "open"
+        @notes = attributes[:notes]
+        @detected_at = attributes[:detected_at]
+        @resolved_at = attributes[:resolved_at]
+
+        validate!
+        freeze
+      end
+
+      def open?
+        status == "open"
+      end
+
+      def resolved?
+        status == "resolved"
+      end
+
+      def to_h
+        {
+          id: id,
+          fact_a_id: fact_a_id,
+          fact_b_id: fact_b_id,
+          status: status,
+          notes: notes,
+          detected_at: detected_at,
+          resolved_at: resolved_at
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "fact_a_id required" if fact_a_id.nil?
+        raise ArgumentError, "fact_b_id required" if fact_b_id.nil?
+      end
+    end
+  end
+end

data/lib/claude_memory/domain/entity.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Domain
+    # Domain model representing an entity (database, framework, person, etc.)
+    class Entity
+      attr_reader :id, :type, :canonical_name, :slug, :created_at
+
+      def initialize(attributes)
+        @id = attributes[:id]
+        @type = attributes[:type]
+        @canonical_name = attributes[:canonical_name]
+        @slug = attributes[:slug]
+        @created_at = attributes[:created_at]
+
+        validate!
+        freeze
+      end
+
+      def database?
+        type == "database"
+      end
+
+      def framework?
+        type == "framework"
+      end
+
+      def person?
+        type == "person"
+      end
+
+      def to_h
+        {
+          id: id,
+          type: type,
+          canonical_name: canonical_name,
+          slug: slug,
+          created_at: created_at
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "type required" if type.nil? || type.empty?
+        raise ArgumentError, "canonical_name required" if canonical_name.nil? || canonical_name.empty?
+        raise ArgumentError, "slug required" if slug.nil? || slug.empty?
+      end
+    end
+  end
+end

data/lib/claude_memory/domain/fact.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Domain
+    # Domain model representing a fact in the memory system
+    # Encapsulates business logic and validation
+    class Fact
+      attr_reader :id, :subject_name, :predicate, :object_literal,
+        :status, :confidence, :scope, :project_path,
+        :valid_from, :valid_to, :created_at
+
+      def initialize(attributes)
+        @id = attributes[:id]
+        @subject_name = attributes[:subject_name]
+        @predicate = attributes[:predicate]
+        @object_literal = attributes[:object_literal]
+        @status = attributes[:status] || "active"
+        @confidence = attributes[:confidence] || 1.0
+        @scope = attributes[:scope] || "project"
+        @project_path = attributes[:project_path]
+        @valid_from = attributes[:valid_from]
+        @valid_to = attributes[:valid_to]
+        @created_at = attributes[:created_at]
+
+        validate!
+        freeze
+      end
+
+      def active?
+        status == "active"
+      end
+
+      def superseded?
+        status == "superseded"
+      end
+
+      def global?
+        scope == "global"
+      end
+
+      def project?
+        scope == "project"
+      end
+
+      def to_h
+        {
+          id: id,
+          subject_name: subject_name,
+          predicate: predicate,
+          object_literal: object_literal,
+          status: status,
+          confidence: confidence,
+          scope: scope,
+          project_path: project_path,
+          valid_from: valid_from,
+          valid_to: valid_to,
+          created_at: created_at
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "predicate required" if predicate.nil? || predicate.empty?
+        raise ArgumentError, "object_literal required" if object_literal.nil? || object_literal.empty?
+        raise ArgumentError, "confidence must be between 0 and 1" unless (0..1).cover?(confidence)
+      end
+    end
+  end
+end

data/lib/claude_memory/domain/provenance.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Domain
+    # Domain model representing provenance (evidence) for a fact
+    class Provenance
+      attr_reader :id, :fact_id, :content_item_id, :quote, :strength, :created_at
+
+      def initialize(attributes)
+        @id = attributes[:id]
+        @fact_id = attributes[:fact_id]
+        @content_item_id = attributes[:content_item_id]
+        @quote = attributes[:quote]
+        @strength = attributes[:strength] || "stated"
+        @created_at = attributes[:created_at]
+
+        validate!
+        freeze
+      end
+
+      def stated?
+        strength == "stated"
+      end
+
+      def inferred?
+        strength == "inferred"
+      end
+
+      def to_h
+        {
+          id: id,
+          fact_id: fact_id,
+          content_item_id: content_item_id,
+          quote: quote,
+          strength: strength,
+          created_at: created_at
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "fact_id required" if fact_id.nil?
+        raise ArgumentError, "content_item_id required" if content_item_id.nil?
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/exit_codes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Hook
+    module ExitCodes
+      # Success or graceful shutdown
+      SUCCESS = 0
+
+      # Non-blocking error (shown to user, session continues)
+      # Example: Missing transcript file, database not initialized
+      WARNING = 1
+
+      # Blocking error (fed to Claude for processing)
+      # Example: Database corruption, schema mismatch
+      ERROR = 2
+    end
+  end
+end

data/lib/claude_memory/hook/handler.rb

@@ -3,7 +3,7 @@
 module ClaudeMemory
   module Hook
     class Handler
-      class PayloadError < Error; end
+      class PayloadError < ClaudeMemory::Error; end
 
       DEFAULT_SWEEP_BUDGET = 5
 
@@ -27,6 +27,10 @@ module ClaudeMemory
           transcript_path: transcript_path,
           project_path: project_path
         )
+      rescue Ingest::TranscriptReader::FileNotFoundError => e
+        # Transcript file doesn't exist (e.g., headless Claude session)
+        # This is expected, not an error - return success with no-op status
+        {status: :skipped, reason: "transcript_not_found", message: e.message}
       end
 
       def sweep(payload)
@@ -40,9 +44,10 @@ module ClaudeMemory
       def publish(payload)
         mode = payload.fetch("mode", "shared").to_sym
         since = payload["since"]
+        rules_dir = payload["rules_dir"]
 
         publisher = Publish.new(@store)
-        publisher.publish!(mode: mode, since: since)
+        publisher.publish!(mode: mode, since: since, rules_dir: rules_dir)
       end
     end
   end

data/lib/claude_memory/index/index_query.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Index
+    class IndexQuery
+      def initialize(store, options)
+        @store = store
+        @options = options
+        @fts = LexicalFTS.new(store)
+      end
+
+      def execute
+        # Query 1: Search FTS for content IDs (1 query)
+        content_ids = search_content
+
+        return [] if content_ids.empty?
+
+        # Query 2: Batch fetch ALL provenance records (1 query, not N!)
+        provenance_by_content = fetch_all_provenance(content_ids)
+
+        # Pure logic: collect fact IDs (no I/O)
+        fact_ids = IndexQueryLogic.collect_fact_ids(
+          provenance_by_content,
+          content_ids,
+          @options.limit
+        )
+
+        return [] if fact_ids.empty?
+
+        # Query 3: Batch fetch facts with entities (1 query, not N!)
+        fetch_facts(fact_ids)
+      end
+
+      private
+
+      def search_content
+        # Fetch 3x limit of content to ensure enough facts after deduplication
+        @fts.search(@options.query_text, limit: @options.limit * 3)
+      end
+
+      def fetch_all_provenance(content_ids)
+        # Batch query: fetch ALL provenance records at once using WHERE IN
+        # This replaces N individual queries (one per content_id)
+        @store.provenance
+          .select(:fact_id, :content_item_id)
+          .where(content_item_id: content_ids)
+          .all
+          .group_by { |p| p[:content_item_id] }
+      end
+
+      def fetch_facts(fact_ids)
+        # Batch query: fetch ALL facts at once using WHERE IN
+        # This replaces N individual queries (one per 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][:scope],
+            Sequel[:facts][:confidence],
+            Sequel[:entities][:canonical_name].as(:subject_name)
+          )
+          .where(Sequel[:facts][:id] => fact_ids)
+          .all
+          .map do |fact|
+            {
+              id: fact[:id],
+              subject: fact[:subject_name],
+              predicate: fact[:predicate],
+              object_preview: truncate_preview(fact[:object_literal]),
+              status: fact[:status],
+              scope: fact[:scope],
+              confidence: fact[:confidence],
+              token_estimate: Core::TokenEstimator.estimate_fact(fact),
+              source: @options.source
+            }
+          end
+      end
+
+      def truncate_preview(text)
+        return nil if text.nil?
+        return text if text.length <= 50
+        text[0, 50]
+      end
+    end
+  end
+end

data/lib/claude_memory/index/index_query_logic.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Index
+    module IndexQueryLogic
+      # Pure function: collects fact IDs from provenance records
+      # No I/O, no side effects - fully testable
+      #
+      # @param provenance_by_content [Hash] Map of content_item_id => array of provenance records
+      # @param content_ids [Array<Integer>] Content IDs in FTS relevance order
+      # @param limit [Integer] Maximum number of fact IDs to collect
+      # @return [Array<Integer>] Ordered, deduplicated fact IDs
+      def self.collect_fact_ids(provenance_by_content, content_ids, limit)
+        return [] if limit <= 0
+        return [] if content_ids.empty?
+
+        seen_fact_ids = Set.new
+        ordered_fact_ids = []
+
+        content_ids.each do |content_id|
+          provenance_records = provenance_by_content[content_id]
+          next unless provenance_records
+
+          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
+    end
+  end
+end