claude_memory 0.4.0 → 0.5.0

data/lib/claude_memory/commands/doctor_command.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
+require "optparse"
+
 module ClaudeMemory
   module Commands
     # Performs system health checks for ClaudeMemory
     # Delegates to specialized check classes for actual validation
     class DoctorCommand < BaseCommand
-      def call(_args)
+      def call(args)
+        opts = parse_options(args, {brief: false}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--brief", "Output single-line status summary") { o[:brief] = true }
+          end
+        end
+        return 1 if opts.nil?
+
         manager = ClaudeMemory::Store::StoreManager.new
 
         checks = [
@@ -20,10 +29,42 @@ module ClaudeMemory
 
         manager.close
 
-        reporter = Checks::Reporter.new(stdout, stderr)
-        success = reporter.report(results)
+        if opts[:brief]
+          report_brief(results)
+        else
+          reporter = Checks::Reporter.new(stdout, stderr)
+          success = reporter.report(results)
+          success ? 0 : 1
+        end
+      end
+
+      private
+
+      def report_brief(results)
+        errors = results.select { |r| r[:status] == :error }
+        warnings = results.select { |r| r[:status] == :warning }
+
+        if errors.any?
+          messages = errors.map { |e| e[:message] }
+          stdout.puts "Memory ERROR: #{messages.join(", ")}"
+          return 1
+        end
+
+        fact_parts = results
+          .select { |r| r[:label] =~ /global|project/ && r.dig(:details, :fact_count) }
+          .map { |r| "#{r.dig(:details, :fact_count)} facts (#{r[:label]})" }
+
+        status = warnings.any? ? "WARNING" : "OK"
+        summary = fact_parts.any? ? fact_parts.join(", ") : "no databases"
+
+        if warnings.any?
+          warning_msgs = warnings.map { |w| w[:message] }.join("; ")
+          stdout.puts "Memory #{status}: #{summary} [#{warning_msgs}]"
+        else
+          stdout.puts "Memory #{status}: #{summary}"
+        end
 
-        success ? 0 : 1
+        0
       end
     end
   end

data/lib/claude_memory/commands/explain_command.rb

@@ -5,12 +5,15 @@ module ClaudeMemory
     # Explains a fact with provenance and relationships
     class ExplainCommand < BaseCommand
       def call(args)
-        fact_id = args.first&.to_i
-        unless fact_id && fact_id > 0
-          stderr.puts "Usage: claude-memory explain <fact_id> [--scope project|global]"
+        identifier = args.first
+        unless identifier && !identifier.empty?
+          stderr.puts "Usage: claude-memory explain <fact_id|docid> [--scope project|global]"
           return 1
         end
 
+        # Accept integer IDs or 8-char docid strings
+        fact_ref = identifier.match?(/\A\d+\z/) ? identifier.to_i : identifier
+
         opts = parse_options(args[1..] || [], {scope: "project"}) do |o|
           OptionParser.new do |parser|
             parser.on("--scope SCOPE", "Scope: project or global") { |v| o[:scope] = v }
@@ -21,14 +24,16 @@ module ClaudeMemory
         manager = ClaudeMemory::Store::StoreManager.new
         recall = ClaudeMemory::Recall.new(manager)
 
-        explanation = recall.explain(fact_id, scope: opts[:scope])
+        explanation = recall.explain(fact_ref, scope: opts[:scope])
         if explanation.is_a?(ClaudeMemory::Core::NullExplanation)
-          stderr.puts "Fact #{fact_id} not found in #{opts[:scope]} database."
+          stderr.puts "Fact #{identifier} not found in #{opts[:scope]} database."
           manager.close
           return 1
         end
 
-        stdout.puts "Fact ##{fact_id} (#{opts[:scope]}):"
+        docid = explanation[:fact][:docid]
+        label = docid ? "##{docid}" : "##{explanation[:fact][:id]}"
+        stdout.puts "Fact #{label} (#{opts[:scope]}):"
         print_fact(explanation[:fact])
         print_receipts(explanation[:receipts])
 

data/lib/claude_memory/commands/stats_command.rb

@@ -84,7 +84,7 @@ module ClaudeMemory
           stdout.puts
 
           db.disconnect
-        rescue => e
+        rescue Sequel::DatabaseError, Extralite::Error => e
           stderr.puts "Error reading database: #{e.message}"
         end
       end

data/lib/claude_memory/core/fact_graph.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Builds a dependency graph of facts using BFS traversal.
+    # Queries fact_links and conflicts tables to build a graph
+    # of related facts with their relationships.
+    # Follows Functional Core pattern - pure query + transformation.
+    class FactGraph
+      MAX_DEPTH = 5
+
+      # Build a fact dependency graph starting from a root fact
+      # @param store [SQLiteStore] Database store
+      # @param root_fact_id [Integer] Starting fact ID
+      # @param depth [Integer] Maximum BFS depth (1-5)
+      # @return [Hash] Graph with :nodes and :edges arrays
+      def self.build(store, root_fact_id, depth: 2)
+        depth = depth.clamp(1, MAX_DEPTH)
+
+        visited = Set.new
+        queue = [[root_fact_id, 0]]
+        nodes = {}
+        edges = []
+
+        while queue.any?
+          fact_id, current_depth = queue.shift
+          next if visited.include?(fact_id)
+
+          visited.add(fact_id)
+
+          fact = FactQueryBuilder.find_fact(store, fact_id)
+          next unless fact
+
+          nodes[fact_id] = build_node(fact)
+
+          next if current_depth >= depth
+
+          discover_links(store, fact_id, current_depth, visited, queue, edges)
+        end
+
+        deduped = dedupe_edges(edges)
+
+        {
+          root_fact_id: root_fact_id,
+          depth: depth,
+          node_count: nodes.size,
+          edge_count: deduped.size,
+          nodes: nodes.values,
+          edges: deduped
+        }
+      end
+
+      def self.discover_links(store, fact_id, current_depth, visited, queue, edges)
+        discover_supersedes(store, fact_id, current_depth, visited, queue, edges)
+        discover_superseded_by(store, fact_id, current_depth, visited, queue, edges)
+        discover_conflicts(store, fact_id, current_depth, visited, queue, edges)
+      end
+
+      def self.discover_supersedes(store, fact_id, current_depth, visited, queue, edges)
+        store.fact_links
+          .where(from_fact_id: fact_id, link_type: "supersedes")
+          .select_map(:to_fact_id)
+          .each do |target_id|
+            edges << {from: fact_id, to: target_id, type: "supersedes"}
+            queue << [target_id, current_depth + 1] unless visited.include?(target_id)
+          end
+      end
+
+      def self.discover_superseded_by(store, fact_id, current_depth, visited, queue, edges)
+        store.fact_links
+          .where(to_fact_id: fact_id, link_type: "supersedes")
+          .select_map(:from_fact_id)
+          .each do |source_id|
+            edges << {from: source_id, to: fact_id, type: "supersedes"}
+            queue << [source_id, current_depth + 1] unless visited.include?(source_id)
+          end
+      end
+
+      def self.discover_conflicts(store, fact_id, current_depth, visited, queue, edges)
+        store.conflicts
+          .where(fact_a_id: fact_id)
+          .select(:fact_b_id, :status)
+          .all
+          .each do |conflict|
+            edges << {from: fact_id, to: conflict[:fact_b_id], type: "conflicts", status: conflict[:status]}
+            queue << [conflict[:fact_b_id], current_depth + 1] unless visited.include?(conflict[:fact_b_id])
+          end
+
+        store.conflicts
+          .where(fact_b_id: fact_id)
+          .select(:fact_a_id, :status)
+          .all
+          .each do |conflict|
+            edges << {from: conflict[:fact_a_id], to: fact_id, type: "conflicts", status: conflict[:status]}
+            queue << [conflict[:fact_a_id], current_depth + 1] unless visited.include?(conflict[:fact_a_id])
+          end
+      end
+
+      # Build a minimal node representation of a fact
+      # @param fact [Hash] Fact row from database
+      # @return [Hash] Node representation
+      def self.build_node(fact)
+        {
+          id: fact[:id],
+          docid: fact[:docid],
+          subject: fact[:subject_name],
+          predicate: fact[:predicate],
+          object: fact[:object_literal],
+          status: fact[:status],
+          scope: fact[:scope]
+        }
+      end
+
+      # Remove duplicate edges (same from/to/type)
+      # @param edges [Array<Hash>] Edges to deduplicate
+      # @return [Array<Hash>] Deduplicated edges
+      def self.dedupe_edges(edges)
+        edges.uniq { |e| [e[:from], e[:to], e[:type]] }
+      end
+    end
+  end
+end

data/lib/claude_memory/core/fact_query_builder.rb

@@ -23,11 +23,12 @@ module ClaudeMemory
       # 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
+      # @param include_raw_text [Boolean] Include raw_text for snippet extraction
       # @return [Hash] Hash of fact_id => [receipt_rows]
-      def self.batch_find_receipts(store, fact_ids)
+      def self.batch_find_receipts(store, fact_ids, include_raw_text: false)
         return {} if fact_ids.empty?
 
-        results = build_receipts_dataset(store)
+        results = build_receipts_dataset(store, include_raw_text: include_raw_text)
           .where(Sequel[:provenance][:fact_id] => fact_ids)
           .all
 
@@ -47,12 +48,23 @@ module ClaudeMemory
           .first
       end
 
+      # Find single fact by docid with entity join
+      # @param store [SQLiteStore] Database store
+      # @param docid [String] 8-character docid
+      # @return [Hash, nil] Fact row or nil
+      def self.find_fact_by_docid(store, docid)
+        build_facts_dataset(store)
+          .where(Sequel[:facts][:docid] => docid)
+          .first
+      end
+
       # Find receipts for a single fact
       # @param store [SQLiteStore] Database store
       # @param fact_id [Integer] Fact ID
+      # @param include_raw_text [Boolean] Include raw_text for snippet extraction
       # @return [Array<Hash>] Receipt rows
-      def self.find_receipts(store, fact_id)
-        build_receipts_dataset(store)
+      def self.find_receipts(store, fact_id, include_raw_text: false)
+        build_receipts_dataset(store, include_raw_text: include_raw_text)
           .where(Sequel[:provenance][:fact_id] => fact_id)
           .all
       end
@@ -95,7 +107,7 @@ module ClaudeMemory
       # @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)
+          .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)
@@ -121,6 +133,7 @@ module ClaudeMemory
           .left_join(:entities, id: :subject_entity_id)
           .select(
             Sequel[:facts][:id],
+            Sequel[:facts][:docid],
             Sequel[:facts][:predicate],
             Sequel[:facts][:object_literal],
             Sequel[:facts][:status],
@@ -136,18 +149,25 @@ module ClaudeMemory
 
       # Build standard receipts dataset with content_items join
       # @param store [SQLiteStore] Database store
+      # @param include_raw_text [Boolean] Include raw_text for snippet extraction
       # @return [Sequel::Dataset] Configured dataset
-      def self.build_receipts_dataset(store)
+      def self.build_receipts_dataset(store, include_raw_text: false)
+        columns = [
+          Sequel[:provenance][:id],
+          Sequel[:provenance][:fact_id],
+          Sequel[:provenance][:quote],
+          Sequel[:provenance][:strength],
+          Sequel[:provenance][:line_start],
+          Sequel[:provenance][:line_end],
+          Sequel[:content_items][:session_id],
+          Sequel[:content_items][:occurred_at]
+        ]
+
+        columns << Sequel[:content_items][:raw_text] if include_raw_text
+
         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]
-          )
+          .select(*columns)
       end
     end
   end

data/lib/claude_memory/core/fact_ranker.rb

@@ -83,30 +83,13 @@ module ClaudeMemory
         seen.values.sort_by { |r| -r[:similarity] }.take(limit)
       end
 
-      # Merge vector and text search results, preferring vector similarity scores
+      # Merge vector and text search results using Reciprocal Rank Fusion
       # @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
+      # @return [Array<Hash>] Merged results sorted by RRF score 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)
+        RRFusion.fuse(vector_results, text_results, limit)
       end
     end
   end

data/lib/claude_memory/core/relative_time.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Formats timestamps as human-readable relative time strings.
+    # Progressive granularity: just now → Xm ago → Xh ago → Xd ago → date
+    module RelativeTime
+      MINUTE = 60
+      HOUR = 3600
+      DAY = 86400
+
+      def self.format(timestamp, now: Time.now)
+        return nil if timestamp.nil?
+
+        time = parse_time(timestamp)
+        return nil unless time
+
+        diff = now - time
+        return format_absolute(time) if diff.negative?
+
+        case diff
+        when 0...MINUTE then "just now"
+        when MINUTE...HOUR then "#{(diff / MINUTE).to_i}m ago"
+        when HOUR...DAY then "#{(diff / HOUR).to_i}h ago"
+        when DAY...(7 * DAY) then "#{(diff / DAY).to_i}d ago"
+        else format_absolute(time)
+        end
+      end
+
+      def self.parse_time(value)
+        case value
+        when Time then value
+        when String then Time.parse(value)
+        when Integer, Float then Time.at(value)
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def self.format_absolute(time)
+        time.strftime("%Y-%m-%d")
+      end
+    end
+  end
+end

data/lib/claude_memory/core/result_sorter.rb

@@ -16,9 +16,9 @@ module ClaudeMemory
       # 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)
+      # @return [Array<Hash>] New array of results with :source key added
       def self.annotate_source(results, source)
-        results.each { |r| r[:source] = source }
+        results.map { |r| r.merge(source: source) }
       end
     end
   end

data/lib/claude_memory/core/rr_fusion.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Reciprocal Rank Fusion (RRF) for merging ranked result lists
+    # Follows Functional Core pattern - no I/O, just transformations
+    #
+    # RRF combines multiple ranked lists using position-based scoring:
+    #   score(d) = Σ(weight_r / (k + rank_r(d)))
+    #
+    # This is more effective than naive deduplication because it considers
+    # rank positions from both sources, giving higher scores to results
+    # that appear near the top in multiple lists.
+    class RRFusion
+      K = 60 # Standard RRF constant - controls rank pressure
+      TOP_BONUS = {1 => 0.05, 2 => 0.02, 3 => 0.02}.freeze
+
+      # Fuse ranked lists from vector and text search
+      # @param vector_results [Array<Hash>] Results from vector search (ordered by similarity)
+      # @param text_results [Array<Hash>] Results from text search (ordered by FTS rank)
+      # @param limit [Integer] Maximum results to return
+      # @param vector_weight [Float] Weight multiplier for vector rankings (default 1.0)
+      # @param text_weight [Float] Weight multiplier for text rankings (default 1.0)
+      # @return [Array<Hash>] Fused results sorted by RRF score, with :similarity set to RRF score
+      def self.fuse(vector_results, text_results, limit, vector_weight: 1.0, text_weight: 1.0)
+        scores = {}
+        fact_data = {}
+
+        # Score vector results by rank position
+        vector_results.each_with_index do |result, idx|
+          fact_id = result[:fact][:id]
+          rank = idx + 1 # 1-based rank
+          scores[fact_id] = (scores[fact_id] || 0.0) + (vector_weight / (K + rank))
+          scores[fact_id] += TOP_BONUS.fetch(rank, 0.0)
+          # Prefer vector result data (has real similarity score)
+          fact_data[fact_id] = result
+        end
+
+        # Score text results by rank position
+        text_results.each_with_index do |result, idx|
+          fact_id = result[:fact][:id]
+          rank = idx + 1
+          scores[fact_id] = (scores[fact_id] || 0.0) + (text_weight / (K + rank))
+          scores[fact_id] += TOP_BONUS.fetch(rank, 0.0)
+          # Only use text data if not already present from vector
+          fact_data[fact_id] ||= result
+        end
+
+        # Sort by RRF score descending and return top results
+        scores
+          .sort_by { |_id, score| -score }
+          .take(limit)
+          .map { |fact_id, score| fact_data[fact_id].merge(similarity: score) }
+      end
+    end
+  end
+end

data/lib/claude_memory/core/snippet_extractor.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Extracts relevant snippets from raw content based on query terms.
+    # Finds the line with the most query term matches and returns
+    # surrounding context (1 line before + 2 lines after).
+    # Follows Functional Core pattern - pure transformations, no I/O.
+    class SnippetExtractor
+      CONTEXT_BEFORE = 1
+      CONTEXT_AFTER = 2
+      MAX_SNIPPET_LENGTH = 500
+
+      # Extract the best snippet from content matching the query
+      # @param content [String] Raw text content
+      # @param query [String] Search query
+      # @return [String, nil] Best matching snippet or nil if no content
+      def self.extract(content, query)
+        return nil if content.nil? || content.empty? || query.nil? || query.empty?
+
+        lines = content.lines.map(&:chomp)
+        return nil if lines.empty?
+
+        terms = tokenize_query(query)
+        return nil if terms.empty?
+
+        best_line_idx = find_best_line(lines, terms)
+        return nil unless best_line_idx
+
+        build_snippet(lines, best_line_idx)
+      end
+
+      # Extract snippet and return line range information
+      # @param content [String] Raw text content
+      # @param query [String] Search query
+      # @return [Hash, nil] Hash with :snippet, :line_start, :line_end or nil
+      def self.extract_with_lines(content, query)
+        return nil if content.nil? || content.empty? || query.nil? || query.empty?
+
+        lines = content.lines.map(&:chomp)
+        return nil if lines.empty?
+
+        terms = tokenize_query(query)
+        return nil if terms.empty?
+
+        best_line_idx = find_best_line(lines, terms)
+        return nil unless best_line_idx
+
+        start_idx = [best_line_idx - CONTEXT_BEFORE, 0].max
+        end_idx = [best_line_idx + CONTEXT_AFTER, lines.size - 1].min
+
+        {
+          snippet: build_snippet(lines, best_line_idx),
+          line_start: start_idx + 1, # 1-indexed
+          line_end: end_idx + 1       # 1-indexed
+        }
+      end
+
+      # @api private
+      def self.tokenize_query(query)
+        query.downcase.split(/\s+/).reject { |t| t.length < 2 }
+      end
+
+      # @api private
+      def self.find_best_line(lines, terms)
+        best_idx = nil
+        best_score = 0
+
+        lines.each_with_index do |line, idx|
+          downcased = line.downcase
+          score = terms.count { |term| downcased.include?(term) }
+          if score > best_score
+            best_score = score
+            best_idx = idx
+          end
+        end
+
+        best_idx
+      end
+
+      # @api private
+      def self.build_snippet(lines, center_idx)
+        start_idx = [center_idx - CONTEXT_BEFORE, 0].max
+        end_idx = [center_idx + CONTEXT_AFTER, lines.size - 1].min
+
+        snippet = lines[start_idx..end_idx].join("\n")
+        truncate(snippet)
+      end
+
+      # @api private
+      def self.truncate(text)
+        return text if text.length <= MAX_SNIPPET_LENGTH
+        text[0, MAX_SNIPPET_LENGTH - 3] + "..."
+      end
+    end
+  end
+end

data/lib/claude_memory/domain/fact.rb

@@ -5,12 +5,13 @@ module ClaudeMemory
     # Domain model representing a fact in the memory system
     # Encapsulates business logic and validation
     class Fact
-      attr_reader :id, :subject_name, :predicate, :object_literal,
+      attr_reader :id, :docid, :subject_name, :predicate, :object_literal,
         :status, :confidence, :scope, :project_path,
         :valid_from, :valid_to, :created_at
 
       def initialize(attributes)
         @id = attributes[:id]
+        @docid = attributes[:docid]
         @subject_name = attributes[:subject_name]
         @predicate = attributes[:predicate]
         @object_literal = attributes[:object_literal]
@@ -45,6 +46,7 @@ module ClaudeMemory
       def to_h
         {
           id: id,
+          docid: docid,
           subject_name: subject_name,
           predicate: predicate,
           object_literal: object_literal,

data/lib/claude_memory/index/index_query.rb

@@ -55,6 +55,7 @@ module ClaudeMemory
           .left_join(:entities, id: :subject_entity_id)
           .select(
             Sequel[:facts][:id],
+            Sequel[:facts][:docid],
             Sequel[:facts][:predicate],
             Sequel[:facts][:object_literal],
             Sequel[:facts][:status],
@@ -67,6 +68,7 @@ module ClaudeMemory
           .map do |fact|
             {
               id: fact[:id],
+              docid: fact[:docid],
               subject: fact[:subject_name],
               predicate: fact[:predicate],
               object_preview: truncate_preview(fact[:object_literal]),

data/lib/claude_memory/index/lexical_fts.rb

@@ -36,6 +36,24 @@ module ClaudeMemory
           .select_map(:content_item_id)
       end
 
+      # Search returning content IDs with FTS5 BM25 rank values
+      # @param query [String] Search query
+      # @param limit [Integer] Maximum results
+      # @return [Array<Hash>] Results with :content_item_id and :rank
+      def search_with_ranks(query, limit: 20)
+        ensure_fts_table!
+        return [] if query.nil? || query.strip.empty?
+        return [] if query.strip == "*"
+
+        escaped_query = escape_fts_query(query)
+        @db[:content_fts]
+          .where(Sequel.lit("text MATCH ?", escaped_query))
+          .order(:rank)
+          .limit(limit)
+          .select(Sequel.lit("content_item_id, rank"))
+          .all
+      end
+
       def escape_fts_query(query)
         words = query.split(/\s+/).map do |word|
           next word if word == "*"