claude_memory 0.2.0 → 0.3.0

data/lib/claude_memory/commands/initializers/project_initializer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module ClaudeMemory
+  module Commands
+    module Initializers
+      # Orchestrates project-local ClaudeMemory initialization
+      class ProjectInitializer
+        def initialize(stdout, stderr, stdin)
+          @stdout = stdout
+          @stderr = stderr
+          @stdin = stdin
+        end
+
+        def initialize_memory
+          @stdout.puts "Initializing ClaudeMemory (project-local)...\n\n"
+
+          # Check for existing hooks and offer options
+          hooks_config = HooksConfigurator.new(@stdout)
+          if hooks_config.has_claude_memory_hooks?(".claude/settings.json")
+            handle_existing_hooks(hooks_config)
+            return 0 if @skip_initialization
+          end
+
+          ensure_databases
+          ensure_directories
+          configure_hooks unless @skip_hooks
+          configure_mcp
+          configure_memory_instructions
+          install_output_style
+
+          print_completion_message
+          0
+        end
+
+        private
+
+        def handle_existing_hooks(hooks_config)
+          @stdout.puts "⚠️  Existing claude-memory hooks detected in .claude/settings.json"
+          @stdout.puts "\nOptions:"
+          @stdout.puts "  1. Update to current version (recommended)"
+          @stdout.puts "  2. Remove hooks (uninstall)"
+          @stdout.puts "  3. Leave as-is (skip)"
+          @stdout.print "\nChoice [1]: "
+
+          choice = @stdin.gets.to_s.strip
+          choice = "1" if choice.empty?
+
+          case choice
+          when "2"
+            @stdout.puts "\nRemoving hooks..."
+            hooks_config.remove_hooks_from_file(".claude/settings.json")
+            @stdout.puts "✓ Hooks removed. Run 'claude-memory uninstall' for full cleanup."
+            @skip_initialization = true
+          when "3"
+            @stdout.puts "\nSkipping hook configuration."
+            @skip_hooks = true
+          else
+            @stdout.puts "\nUpdating hooks..."
+          end
+        end
+
+        def ensure_databases
+          DatabaseEnsurer.new(@stdout).ensure_project_databases
+        end
+
+        def ensure_directories
+          FileUtils.mkdir_p(".claude/rules")
+          @stdout.puts "✓ Created .claude/rules directory"
+        end
+
+        def configure_hooks
+          HooksConfigurator.new(@stdout).configure_project_hooks
+        end
+
+        def configure_mcp
+          McpConfigurator.new(@stdout).configure_project_mcp
+        end
+
+        def configure_memory_instructions
+          MemoryInstructionsWriter.new(@stdout).write_project_instructions
+        end
+
+        def install_output_style
+          style_source = File.join(__dir__, "../../../output_styles/claude_memory.json")
+          style_dest = ".claude/output_styles/claude_memory.json"
+
+          return unless File.exist?(style_source)
+
+          FileUtils.mkdir_p(File.dirname(style_dest))
+          FileUtils.cp(style_source, style_dest)
+          @stdout.puts "✓ Installed output style at #{style_dest}"
+        end
+
+        def print_completion_message
+          @stdout.puts "\n=== Setup Complete ===\n"
+          @stdout.puts "ClaudeMemory is now configured for this project."
+          @stdout.puts "\nDatabases:"
+          @stdout.puts "  Global: ~/.claude/memory.sqlite3 (user-wide knowledge)"
+          @stdout.puts "  Project: .claude/memory.sqlite3 (project-specific)"
+          @stdout.puts "\nNext steps:"
+          @stdout.puts "  1. Restart Claude Code to load the new configuration"
+          @stdout.puts "  2. Use Claude Code normally - transcripts will be ingested automatically"
+          @stdout.puts "  3. Run 'claude-memory promote <fact_id>' to move facts to global"
+          @stdout.puts "  4. Run 'claude-memory doctor' to verify setup"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/recover_command.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Recovers from stuck operations by resetting them
+    class RecoverCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {operation: nil, scope: nil}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory recover [options]"
+            parser.on("--operation TYPE", "Filter by operation type") { |v| o[:operation] = v }
+            parser.on("--scope SCOPE", "Filter by scope (global/project)") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = Store::StoreManager.new
+
+        total_reset = 0
+
+        # Reset stuck operations in global database
+        if opts[:scope].nil? || opts[:scope] == "global"
+          if File.exist?(manager.global_db_path)
+            count = reset_stuck_operations(
+              manager.global_store,
+              "global",
+              opts[:operation]
+            )
+            total_reset += count
+          end
+        end
+
+        # Reset stuck operations in project database
+        if opts[:scope].nil? || opts[:scope] == "project"
+          if File.exist?(manager.project_db_path)
+            count = reset_stuck_operations(
+              manager.project_store,
+              "project",
+              opts[:operation]
+            )
+            total_reset += count
+          end
+        end
+
+        manager.close
+
+        if total_reset.zero?
+          stdout.puts "No stuck operations found."
+        else
+          stdout.puts "Reset #{total_reset} stuck operation(s)."
+          stdout.puts "You can now re-run the failed operation."
+        end
+
+        0
+      end
+
+      private
+
+      def reset_stuck_operations(store, scope_label, operation_type_filter)
+        tracker = Infrastructure::OperationTracker.new(store)
+
+        count = tracker.reset_stuck_operations(
+          operation_type: operation_type_filter,
+          scope: scope_label
+        )
+
+        if count > 0
+          stdout.puts "#{scope_label.capitalize}: Reset #{count} stuck operation(s)"
+        end
+
+        count
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/registry.rb

@@ -11,6 +11,7 @@ module ClaudeMemory
         "help" => "HelpCommand",
         "version" => "VersionCommand",
         "doctor" => "DoctorCommand",
+        "stats" => "StatsCommand",
         "promote" => "PromoteCommand",
         "search" => "SearchCommand",
         "explain" => "ExplainCommand",
@@ -22,8 +23,11 @@ module ClaudeMemory
         "publish" => "PublishCommand",
         "db:init" => "DbInitCommand",
         "init" => "InitCommand",
+        "uninstall" => "UninstallCommand",
         "serve-mcp" => "ServeMcpCommand",
-        "hook" => "HookCommand"
+        "hook" => "HookCommand",
+        "index" => "IndexCommand",
+        "recover" => "RecoverCommand"
       }.freeze
 
       # Find a command class by name

data/lib/claude_memory/commands/stats_command.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Displays detailed statistics about the memory system
+    # Shows facts by status and predicate, entities by type, content items,
+    # provenance coverage, conflicts, and database sizes
+    class StatsCommand < BaseCommand
+      SCOPE_ALL = "all"
+      SCOPE_GLOBAL = "global"
+      SCOPE_PROJECT = "project"
+
+      def call(args)
+        opts = parse_options(args, {scope: SCOPE_ALL}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory stats [options]"
+            parser.on("--scope SCOPE", ["all", "global", "project"],
+              "Show stats for: all (default), global, or project") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+
+        stdout.puts "ClaudeMemory Statistics"
+        stdout.puts "=" * 50
+        stdout.puts
+
+        if opts[:scope] == SCOPE_ALL || opts[:scope] == SCOPE_GLOBAL
+          print_database_stats("GLOBAL", manager.global_db_path)
+        end
+
+        if opts[:scope] == SCOPE_ALL || opts[:scope] == SCOPE_PROJECT
+          print_database_stats("PROJECT", manager.project_db_path)
+        end
+
+        manager.close
+        0
+      end
+
+      private
+
+      def print_database_stats(label, db_path)
+        stdout.puts "## #{label} DATABASE"
+        stdout.puts
+
+        unless File.exist?(db_path)
+          stdout.puts "Database does not exist: #{db_path}"
+          stdout.puts
+          return
+        end
+
+        begin
+          db = Sequel.sqlite(db_path, readonly: true)
+
+          # Facts statistics
+          print_fact_stats(db)
+          stdout.puts
+
+          # Entities statistics
+          print_entity_stats(db)
+          stdout.puts
+
+          # Content items statistics
+          print_content_stats(db)
+          stdout.puts
+
+          # Provenance coverage
+          print_provenance_stats(db)
+          stdout.puts
+
+          # Conflicts
+          print_conflict_stats(db)
+          stdout.puts
+
+          # ROI Metrics (if available)
+          print_roi_metrics(db)
+          stdout.puts
+
+          # Database size
+          print_database_size(db_path)
+          stdout.puts
+
+          db.disconnect
+        rescue => e
+          stderr.puts "Error reading database: #{e.message}"
+        end
+      end
+
+      def print_fact_stats(db)
+        total = db[:facts].count
+        active = db[:facts].where(status: "active").count
+        superseded = db[:facts].where(status: "superseded").count
+
+        stdout.puts "Facts:"
+        stdout.puts "  Total: #{total} (#{active} active, #{superseded} superseded)"
+
+        if total > 0
+          stdout.puts
+          stdout.puts "  Top Predicates:"
+
+          predicate_counts = db[:facts]
+            .where(status: "active")
+            .group_and_count(:predicate)
+            .order(Sequel.desc(:count))
+            .limit(10)
+            .all
+
+          predicate_counts.each do |row|
+            stdout.puts "    #{row[:count].to_s.rjust(4)} - #{row[:predicate]}"
+          end
+        end
+      end
+
+      def print_entity_stats(db)
+        total = db[:entities].count
+
+        stdout.puts "Entities: #{total}"
+
+        if total > 0
+          type_counts = db[:entities]
+            .group_and_count(:type)
+            .order(Sequel.desc(:count))
+            .all
+
+          type_counts.each do |row|
+            stdout.puts "  #{row[:count].to_s.rjust(4)} - #{row[:type]}"
+          end
+        end
+      end
+
+      def print_content_stats(db)
+        total = db[:content_items].count
+
+        stdout.puts "Content Items: #{total}"
+
+        if total > 0
+          first_date = db[:content_items].min(:occurred_at)
+          last_date = db[:content_items].max(:occurred_at)
+
+          if first_date && last_date
+            first_formatted = format_date(first_date)
+            last_formatted = format_date(last_date)
+            stdout.puts "  Date Range: #{first_formatted} - #{last_formatted}"
+          end
+        end
+      end
+
+      def print_provenance_stats(db)
+        total_active_facts = db[:facts].where(status: "active").count
+        facts_with_provenance = db[:provenance]
+          .join(:facts, id: :fact_id)
+          .where(Sequel[:facts][:status] => "active")
+          .select(Sequel[:provenance][:fact_id])
+          .distinct
+          .count
+
+        if total_active_facts > 0
+          percentage = (facts_with_provenance * 100.0 / total_active_facts).round(1)
+          stdout.puts "Provenance: #{facts_with_provenance}/#{total_active_facts} facts have sources (#{percentage}%)"
+        else
+          stdout.puts "Provenance: 0/0 facts have sources"
+        end
+      end
+
+      def print_conflict_stats(db)
+        open = db[:conflicts].where(status: "open").count
+        resolved = db[:conflicts].where(status: "resolved").count
+        total = open + resolved
+
+        stdout.puts "Conflicts: #{open} open, #{resolved} resolved (#{total} total)"
+      end
+
+      def print_roi_metrics(db)
+        # Check if ingestion_metrics table exists (schema v7+)
+        return unless db.table_exists?(:ingestion_metrics)
+
+        # standard:disable Performance/Detect (Sequel DSL requires .select{}.first)
+        result = db[:ingestion_metrics]
+          .select {
+            [
+              sum(:input_tokens).as(:total_input),
+              sum(:output_tokens).as(:total_output),
+              sum(:facts_extracted).as(:total_facts),
+              count(:id).as(:total_ops)
+            ]
+          }
+          .first
+        # standard:enable Performance/Detect
+
+        return if result.nil? || result[:total_ops].to_i.zero?
+
+        total_input = result[:total_input].to_i
+        total_output = result[:total_output].to_i
+        total_facts = result[:total_facts].to_i
+        total_ops = result[:total_ops].to_i
+
+        efficiency = total_input.zero? ? 0.0 : (total_facts.to_f / total_input * 1000).round(2)
+
+        stdout.puts "Token Economics (Distillation ROI):"
+        stdout.puts "  Input Tokens: #{format_number(total_input)}"
+        stdout.puts "  Output Tokens: #{format_number(total_output)}"
+        stdout.puts "  Facts Extracted: #{format_number(total_facts)}"
+        stdout.puts "  Operations: #{format_number(total_ops)}"
+        stdout.puts "  Efficiency: #{efficiency} facts per 1,000 input tokens"
+      end
+
+      def print_database_size(db_path)
+        size_bytes = File.size(db_path)
+        size_kb = (size_bytes / 1024.0).round(1)
+        size_mb = (size_bytes / (1024.0 * 1024.0)).round(2)
+
+        if size_mb >= 1.0
+          stdout.puts "Database Size: #{size_mb} MB"
+        else
+          stdout.puts "Database Size: #{size_kb} KB"
+        end
+      end
+
+      def format_date(iso8601_string)
+        # Extract just the date part (YYYY-MM-DD) from ISO8601 timestamp
+        return iso8601_string unless iso8601_string
+
+        date_part = iso8601_string.split("T").first
+        return date_part if date_part
+
+        # Fallback to first 10 chars
+        iso8601_string[0...10]
+      end
+
+      def format_number(num)
+        # Format number with comma separators (e.g., 1234567 => "1,234,567")
+        num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/uninstall_command.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # Removes ClaudeMemory configuration from a project or globally
+    class UninstallCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {global: false, full: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory uninstall [options]"
+            parser.on("--global", "Uninstall from global ~/.claude/ settings") { o[:global] = true }
+            parser.on("--full", "Remove databases and all configuration (not just hooks)") { o[:full] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        if opts[:global]
+          uninstall_global(opts[:full])
+        else
+          uninstall_local(opts[:full])
+        end
+      end
+
+      private
+
+      def uninstall_local(full)
+        stdout.puts "Uninstalling ClaudeMemory (project-local)...\n\n"
+
+        removed_items = []
+
+        # Remove hooks from settings.json
+        if remove_hooks_from_file(".claude/settings.json")
+          removed_items << "Hooks from .claude/settings.json"
+        end
+
+        # Remove MCP server from .claude.json
+        if remove_mcp_server(".claude.json")
+          removed_items << "MCP server from .claude.json"
+        end
+
+        # Remove ClaudeMemory section from .claude/CLAUDE.md
+        if remove_claude_md_section(".claude/CLAUDE.md")
+          removed_items << "ClaudeMemory section from .claude/CLAUDE.md"
+        end
+
+        if full
+          # Remove databases and generated files
+          files_to_remove = [
+            ".claude/memory.sqlite3",
+            ".claude/rules/claude_memory.generated.md",
+            ".claude/output_styles/claude_memory.json"
+          ]
+
+          files_to_remove.each do |file|
+            if File.exist?(file)
+              FileUtils.rm_f(file)
+              removed_items << "Removed #{file}"
+            end
+          end
+        end
+
+        stdout.puts "\n=== Uninstall Complete ===\n"
+        if removed_items.any?
+          stdout.puts "Removed:"
+          removed_items.each { |item| stdout.puts "  ✓ #{item}" }
+        else
+          stdout.puts "No ClaudeMemory configuration found."
+        end
+
+        if full
+          stdout.puts "\nNote: Global database (~/.claude/memory.sqlite3) was NOT removed."
+          stdout.puts "      Run 'claude-memory uninstall --global --full' to remove it."
+        else
+          stdout.puts "\nNote: Project database (.claude/memory.sqlite3) was NOT removed."
+          stdout.puts "      Run with --full flag to remove all files."
+        end
+
+        stdout.puts "\nRestart Claude Code to complete uninstallation."
+
+        0
+      end
+
+      def uninstall_global(full)
+        stdout.puts "Uninstalling ClaudeMemory (global)...\n\n"
+
+        removed_items = []
+
+        # Remove hooks from ~/.claude/settings.json
+        global_settings = File.join(Dir.home, ".claude", "settings.json")
+        if remove_hooks_from_file(global_settings)
+          removed_items << "Hooks from #{global_settings}"
+        end
+
+        # Remove MCP server from ~/.claude.json
+        global_mcp = File.join(Dir.home, ".claude.json")
+        if remove_mcp_server(global_mcp)
+          removed_items << "MCP server from #{global_mcp}"
+        end
+
+        # Remove ClaudeMemory section from ~/.claude/CLAUDE.md
+        global_claude_md = File.join(Dir.home, ".claude", "CLAUDE.md")
+        if remove_claude_md_section(global_claude_md)
+          removed_items << "ClaudeMemory section from #{global_claude_md}"
+        end
+
+        if full
+          # Remove global database
+          global_db = ClaudeMemory.global_db_path
+          if File.exist?(global_db)
+            FileUtils.rm_f(global_db)
+            removed_items << "Removed #{global_db}"
+          end
+        end
+
+        stdout.puts "\n=== Global Uninstall Complete ===\n"
+        if removed_items.any?
+          stdout.puts "Removed:"
+          removed_items.each { |item| stdout.puts "  ✓ #{item}" }
+        else
+          stdout.puts "No ClaudeMemory configuration found."
+        end
+
+        if full
+          stdout.puts "\nWarning: Global database was removed. All user-wide knowledge is deleted."
+        else
+          stdout.puts "\nNote: Global database (~/.claude/memory.sqlite3) was NOT removed."
+          stdout.puts "      Run with --full flag to remove all files."
+        end
+
+        stdout.puts "\nRestart Claude Code to complete uninstallation."
+
+        0
+      end
+
+      # Removes claude-memory hooks from a settings.json file
+      # Returns true if hooks were removed, false otherwise
+      def remove_hooks_from_file(settings_path)
+        return false unless File.exist?(settings_path)
+
+        begin
+          config = JSON.parse(File.read(settings_path))
+        rescue JSON::ParserError
+          stderr.puts "Warning: Could not parse #{settings_path}, skipping hook removal"
+          return false
+        end
+
+        return false unless config["hooks"]
+
+        modified = false
+        config["hooks"].each do |event, hook_arrays|
+          next unless hook_arrays.is_a?(Array)
+
+          # Filter out hook arrays that contain claude-memory commands
+          original_count = hook_arrays.size
+          hook_arrays.reject! do |hook_array|
+            next false unless hook_array["hooks"].is_a?(Array)
+
+            hook_array["hooks"].any? { |h| h["command"]&.include?("claude-memory") }
+          end
+
+          modified = true if hook_arrays.size < original_count
+
+          # Remove empty event keys
+          config["hooks"].delete(event) if hook_arrays.empty?
+        end
+
+        if modified
+          # Remove hooks key entirely if empty
+          config.delete("hooks") if config["hooks"].empty?
+
+          File.write(settings_path, JSON.pretty_generate(config))
+          true
+        else
+          false
+        end
+      end
+
+      # Removes claude-memory MCP server from .claude.json
+      # Returns true if server was removed, false otherwise
+      def remove_mcp_server(mcp_path)
+        return false unless File.exist?(mcp_path)
+
+        begin
+          config = JSON.parse(File.read(mcp_path))
+        rescue JSON::ParserError
+          stderr.puts "Warning: Could not parse #{mcp_path}, skipping MCP removal"
+          return false
+        end
+
+        return false unless config["mcpServers"]&.key?("claude-memory")
+
+        config["mcpServers"].delete("claude-memory")
+        config.delete("mcpServers") if config["mcpServers"].empty?
+
+        File.write(mcp_path, JSON.pretty_generate(config))
+        true
+      end
+
+      # Removes ClaudeMemory section from CLAUDE.md
+      # Returns true if section was removed, false otherwise
+      def remove_claude_md_section(claude_md_path)
+        return false unless File.exist?(claude_md_path)
+
+        content = File.read(claude_md_path)
+        return false unless content.include?("ClaudeMemory")
+
+        # Remove ClaudeMemory section (marked by HTML comment through end of section)
+        # Match from HTML comment through content until we hit another HTML comment or ## header
+        modified_content = content.gsub(/<!-- ClaudeMemory v.*?-->.*?(?=^##|\n<!--|\Z)/m, "")
+
+        # Clean up extra blank lines
+        modified_content = modified_content.gsub(/\n{3,}/, "\n\n").strip
+
+        if modified_content != content
+          File.write(claude_md_path, modified_content)
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/core/batch_loader.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Utility for batch loading records from Sequel datasets
+    # Eliminates duplication of batch query patterns
+    class BatchLoader
+      # Load multiple records by IDs and organize them by a key
+      #
+      # @param dataset [Sequel::Dataset] The dataset to query
+      # @param ids [Array] The IDs to load
+      # @param group_by [Symbol] How to organize results (:single for hash by ID, or column name for grouping)
+      # @return [Hash] Results organized by the specified key
+      def self.load_many(dataset, ids, group_by: :id)
+        return {} if ids.empty?
+
+        results = dataset.where(id: ids).all
+
+        case group_by
+        when :single
+          # Single record per ID (hash by ID)
+          results.each_with_object({}) { |row, hash| hash[row[:id]] = row }
+        when Symbol
+          # Multiple records per key (grouped)
+          results.group_by { |row| row[group_by] }
+        else
+          raise ArgumentError, "Invalid group_by: #{group_by.inspect}"
+        end
+      end
+    end
+  end
+end