claude_memory 0.1.0 → 0.2.0

data/lib/claude_memory/commands/base_command.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Base class for all CLI commands.
+    # Provides consistent interface for commands with I/O isolation for testing.
+    #
+    # @example Implementing a command
+    #   class MyCommand < BaseCommand
+    #     def call(args)
+    #       opts = parse_options(args, {verbose: false}) do |o|
+    #         OptionParser.new do |parser|
+    #           parser.on("-v", "--verbose") { o[:verbose] = true }
+    #         end
+    #       end
+    #       return 1 if opts.nil?
+    #
+    #       # ... command logic ...
+    #       success("Done!")
+    #     end
+    #   end
+    #
+    # @example Testing a command
+    #   stdout = StringIO.new
+    #   stderr = StringIO.new
+    #   command = MyCommand.new(stdout: stdout, stderr: stderr)
+    #   exit_code = command.call(["--verbose"])
+    #   expect(exit_code).to eq(0)
+    #   expect(stdout.string).to include("Done!")
+    class BaseCommand
+      attr_reader :stdout, :stderr, :stdin
+
+      # @param stdout [IO] output stream (default: $stdout)
+      # @param stderr [IO] error stream (default: $stderr)
+      # @param stdin [IO] input stream (default: $stdin)
+      def initialize(stdout: $stdout, stderr: $stderr, stdin: $stdin)
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = stdin
+      end
+
+      # Execute the command with given arguments
+      # @param args [Array<String>] command line arguments
+      # @return [Integer] exit code (0 for success, non-zero for failure)
+      def call(args)
+        raise NotImplementedError, "Subclass must implement #call"
+      end
+
+      protected
+
+      # Report successful command execution
+      # @param message [String, nil] optional success message
+      # @param exit_code [Integer] exit code (default: 0)
+      # @return [Integer] the exit code
+      def success(message = nil, exit_code: 0)
+        stdout.puts(message) if message
+        exit_code
+      end
+
+      # Report failed command execution
+      # @param message [String] error message
+      # @param exit_code [Integer] exit code (default: 1)
+      # @return [Integer] the exit code
+      def failure(message, exit_code: 1)
+        stderr.puts(message)
+        exit_code
+      end
+
+      # Parse command line options with error handling
+      # @param args [Array<String>] command line arguments
+      # @param defaults [Hash] default option values
+      # @yield [Hash] yields the options hash to configure the parser
+      # @return [Hash, nil] parsed options, or nil if parsing failed
+      #
+      # @example
+      #   opts = parse_options(args, {verbose: false}) do |o|
+      #     OptionParser.new do |parser|
+      #       parser.on("-v", "--verbose") { o[:verbose] = true }
+      #       parser.on("--name NAME") { |v| o[:name] = v }
+      #     end
+      #   end
+      def parse_options(args, defaults = {})
+        opts = defaults.dup
+        parser = yield(opts)
+        parser.parse(args)
+        opts
+      rescue OptionParser::InvalidOption => e
+        failure(e.message)
+        nil
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/changes_command.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Shows recent fact changes
+    class ChangesCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {since: nil, limit: 20, scope: "all"}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--since ISO", "Since timestamp") { |v| o[:since] = v }
+            parser.on("--limit N", Integer, "Max results") { |v| o[:limit] = v }
+            parser.on("--scope SCOPE", "Scope: project, global, or all") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        opts[:since] ||= (Time.now - 86400 * 7).utc.iso8601
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        recall = ClaudeMemory::Recall.new(manager)
+
+        changes = recall.changes(since: opts[:since], limit: opts[:limit], scope: opts[:scope])
+        if changes.empty?
+          stdout.puts "No changes since #{opts[:since]}."
+        else
+          stdout.puts "Changes since #{opts[:since]} (#{changes.size}):\n\n"
+          changes.each do |change|
+            source_label = change[:source] ? " [#{change[:source]}]" : ""
+            stdout.puts "  [#{change[:id]}] #{change[:predicate]}: #{change[:object_literal]} (#{change[:status]})#{source_label}"
+            stdout.puts "    Created: #{change[:created_at]}"
+          end
+        end
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/conflicts_command.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Shows open conflicts in memory
+    class ConflictsCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {scope: "all"}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--scope SCOPE", "Scope: project, global, or all") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        recall = ClaudeMemory::Recall.new(manager)
+        conflicts = recall.conflicts(scope: opts[:scope])
+
+        if conflicts.empty?
+          stdout.puts "No open conflicts."
+        else
+          stdout.puts "Open conflicts (#{conflicts.size}):\n\n"
+          conflicts.each do |c|
+            source_label = c[:source] ? " [#{c[:source]}]" : ""
+            stdout.puts "  Conflict ##{c[:id]}: Fact #{c[:fact_a_id]} vs Fact #{c[:fact_b_id]}#{source_label}"
+            stdout.puts "    Status: #{c[:status]}, Detected: #{c[:detected_at]}"
+            stdout.puts "    Notes: #{c[:notes]}" if c[:notes]
+            stdout.puts
+          end
+        end
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/db_init_command.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Initializes SQLite databases
+    class DbInitCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {global: false, project: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory db:init [options]"
+            parser.on("--global", "Initialize global database (~/.claude/memory.sqlite3)") { o[:global] = true }
+            parser.on("--project", "Initialize project database (.claude/memory.sqlite3)") { o[:project] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        # If neither flag specified, initialize both
+        opts[:global] = true if !opts[:global] && !opts[:project]
+        opts[:project] = true if !opts[:global] && !opts[:project]
+
+        manager = ClaudeMemory::Store::StoreManager.new
+
+        if opts[:global]
+          manager.ensure_global!
+          stdout.puts "Global database initialized at #{manager.global_db_path}"
+          stdout.puts "Schema version: #{manager.global_store.schema_version}"
+        end
+
+        if opts[:project]
+          manager.ensure_project!
+          stdout.puts "Project database initialized at #{manager.project_db_path}"
+          stdout.puts "Schema version: #{manager.project_store.schema_version}"
+        end
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/doctor_command.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # Performs system health checks for ClaudeMemory
+    # Checks databases, snapshots, hooks configuration
+    class DoctorCommand < BaseCommand
+      def call(_args)
+        issues = []
+        warnings = []
+
+        stdout.puts "Claude Memory Doctor\n"
+        stdout.puts "=" * 40
+
+        manager = ClaudeMemory::Store::StoreManager.new
+
+        stdout.puts "\n## Global Database"
+        check_database(manager.global_db_path, "global", issues, warnings)
+
+        stdout.puts "\n## Project Database"
+        check_database(manager.project_db_path, "project", issues, warnings)
+
+        manager.close
+
+        check_snapshot(warnings)
+        check_claude_md(warnings)
+        check_hooks_config(warnings)
+
+        stdout.puts
+
+        if warnings.any?
+          stdout.puts "Warnings:"
+          warnings.each { |w| stdout.puts "  ⚠ #{w}" }
+          stdout.puts
+        end
+
+        if issues.any?
+          stdout.puts "Issues:"
+          issues.each { |i| stderr.puts "  ✗ #{i}" }
+          stdout.puts
+          stdout.puts "Run 'claude-memory init' to set up."
+          return 1
+        end
+
+        stdout.puts "All checks passed!"
+        0
+      end
+
+      private
+
+      def check_database(db_path, label, issues, warnings)
+        if File.exist?(db_path)
+          stdout.puts "✓ #{label.capitalize} database exists: #{db_path}"
+          begin
+            store = ClaudeMemory::Store::SQLiteStore.new(db_path)
+            stdout.puts "  Schema version: #{store.schema_version}"
+
+            fact_count = store.facts.count
+            stdout.puts "  Facts: #{fact_count}"
+
+            content_count = store.content_items.count
+            stdout.puts "  Content items: #{content_count}"
+
+            conflict_count = store.conflicts.where(status: "open").count
+            if conflict_count > 0
+              warnings << "#{label}: #{conflict_count} open conflict(s) need resolution"
+            end
+            stdout.puts "  Open conflicts: #{conflict_count}"
+
+            last_ingest = store.content_items.max(:ingested_at)
+            if last_ingest
+              stdout.puts "  Last ingest: #{last_ingest}"
+            elsif label == "project"
+              warnings << "#{label}: No content has been ingested yet"
+            end
+
+            store.close
+          rescue => e
+            issues << "#{label} database error: #{e.message}"
+          end
+        elsif label == "global"
+          issues << "Global database not found: #{db_path}"
+        else
+          warnings << "Project database not found: #{db_path} (run 'claude-memory init')"
+        end
+      end
+
+      def check_snapshot(warnings)
+        if File.exist?(".claude/rules/claude_memory.generated.md")
+          stdout.puts "✓ Published snapshot exists"
+        else
+          warnings << "No published snapshot found. Run 'claude-memory publish'"
+        end
+      end
+
+      def check_claude_md(warnings)
+        if File.exist?(".claude/CLAUDE.md")
+          content = File.read(".claude/CLAUDE.md")
+          if content.include?("claude_memory.generated.md")
+            stdout.puts "✓ CLAUDE.md imports snapshot"
+          else
+            warnings << "CLAUDE.md does not import snapshot"
+          end
+        else
+          warnings << "No .claude/CLAUDE.md found"
+        end
+      end
+
+      def check_hooks_config(warnings)
+        settings_path = ".claude/settings.json"
+        local_settings_path = ".claude/settings.local.json"
+
+        hooks_found = false
+
+        [settings_path, local_settings_path].each do |path|
+          next unless File.exist?(path)
+
+          begin
+            config = JSON.parse(File.read(path))
+            if config["hooks"]&.any?
+              hooks_found = true
+              stdout.puts "✓ Hooks configured in #{path}"
+
+              expected_hooks = %w[Stop SessionStart PreCompact SessionEnd]
+              missing = expected_hooks - config["hooks"].keys
+              if missing.any?
+                warnings << "Missing recommended hooks in #{path}: #{missing.join(", ")}"
+              end
+            end
+          rescue JSON::ParserError
+            warnings << "Invalid JSON in #{path}"
+          end
+        end
+
+        unless hooks_found
+          warnings << "No hooks configured. Run 'claude-memory init' or configure manually."
+          stdout.puts "\n  Manual fallback available:"
+          stdout.puts "    claude-memory ingest --session-id <id> --transcript-path <path>"
+          stdout.puts "    claude-memory sweep --budget 5"
+          stdout.puts "    claude-memory publish"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/explain_command.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # 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]"
+          return 1
+        end
+
+        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 }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        recall = ClaudeMemory::Recall.new(manager)
+
+        explanation = recall.explain(fact_id, scope: opts[:scope])
+        if explanation.is_a?(ClaudeMemory::Core::NullExplanation)
+          stderr.puts "Fact #{fact_id} not found in #{opts[:scope]} database."
+          manager.close
+          return 1
+        end
+
+        stdout.puts "Fact ##{fact_id} (#{opts[:scope]}):"
+        print_fact(explanation[:fact])
+        print_receipts(explanation[:receipts])
+
+        if explanation[:supersedes].any?
+          stdout.puts "  Supersedes: #{explanation[:supersedes].join(", ")}"
+        end
+        if explanation[:superseded_by].any?
+          stdout.puts "  Superseded by: #{explanation[:superseded_by].join(", ")}"
+        end
+        if explanation[:conflicts].any?
+          stdout.puts "  Conflicts: #{explanation[:conflicts].map { |c| c[:id] }.join(", ")}"
+        end
+
+        manager.close
+        0
+      end
+
+      private
+
+      def print_fact(fact)
+        stdout.puts "  #{fact[:predicate]}: #{fact[:object_literal]}"
+        stdout.puts "    Status: #{fact[:status]}, Confidence: #{fact[:confidence]}"
+      end
+
+      def print_receipts(receipts)
+        return if receipts.empty?
+        stdout.puts "  Receipts (#{receipts.size}):"
+        receipts.each do |r|
+          stdout.puts "    - #{r[:quote] || "(no quote)"}"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/help_command.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Displays help information for claude-memory CLI
+    class HelpCommand < BaseCommand
+      def call(_args)
+        stdout.puts <<~HELP
+          claude-memory - Long-term memory for Claude Code
+
+          Usage: claude-memory <command> [options]
+
+          Commands:
+            changes    Show recent fact changes
+            conflicts  Show open conflicts
+            db:init    Initialize the SQLite database
+            doctor     Check system health
+            explain    Explain a fact with receipts
+            help       Show this help message
+            hook       Run hook entrypoints (ingest|sweep|publish)
+            init       Initialize ClaudeMemory in a project
+            ingest     Ingest transcript delta
+            promote    Promote a project fact to global memory
+            publish    Publish snapshot to Claude Code memory
+            recall     Recall facts matching a query
+            search     Search indexed content
+            serve-mcp  Start MCP server
+            sweep      Run maintenance/pruning
+            version    Show version number
+
+          Run 'claude-memory <command> --help' for more information on a command.
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/hook_command.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # Handles hook entrypoints (ingest, sweep, publish)
+    class HookCommand < BaseCommand
+      def call(args)
+        subcommand = args.first
+
+        unless subcommand
+          stderr.puts "Usage: claude-memory hook <ingest|sweep|publish> [options]"
+          stderr.puts "\nReads hook payload JSON from stdin."
+          return Hook::ExitCodes::ERROR
+        end
+
+        unless %w[ingest sweep publish].include?(subcommand)
+          stderr.puts "Unknown hook command: #{subcommand}"
+          stderr.puts "Available: ingest, sweep, publish"
+          return Hook::ExitCodes::ERROR
+        end
+
+        opts = parse_options(args[1..] || [], {db: ClaudeMemory.project_db_path}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--db PATH", "Database path") { |v| o[:db] = v }
+          end
+        end
+        return Hook::ExitCodes::ERROR if opts.nil?
+
+        payload = parse_hook_payload
+        return Hook::ExitCodes::ERROR unless payload
+
+        store = ClaudeMemory::Store::SQLiteStore.new(opts[:db])
+        handler = ClaudeMemory::Hook::Handler.new(store)
+
+        exit_code = case subcommand
+        when "ingest"
+          hook_ingest(handler, payload)
+        when "sweep"
+          hook_sweep(handler, payload)
+        when "publish"
+          hook_publish(handler, payload)
+        end
+
+        store.close
+        exit_code
+      rescue ClaudeMemory::Hook::Handler::PayloadError => e
+        stderr.puts "Payload error: #{e.message}"
+        Hook::ExitCodes::ERROR
+      end
+
+      private
+
+      def parse_hook_payload
+        input = stdin.read
+        JSON.parse(input)
+      rescue JSON::ParserError => e
+        stderr.puts "Invalid JSON payload: #{e.message}"
+        nil
+      end
+
+      def hook_ingest(handler, payload)
+        result = handler.ingest(payload)
+
+        case result[:status]
+        when :ingested
+          stdout.puts "Ingested #{result[:bytes_read]} bytes (content_id: #{result[:content_id]})"
+          Hook::ExitCodes::SUCCESS
+        when :no_change
+          stdout.puts "No new content to ingest"
+          Hook::ExitCodes::SUCCESS
+        when :skipped
+          stdout.puts "Skipped ingestion: #{result[:reason]}"
+          Hook::ExitCodes::WARNING
+        else
+          Hook::ExitCodes::ERROR
+        end
+      end
+
+      def hook_sweep(handler, payload)
+        result = handler.sweep(payload)
+        stats = result[:stats]
+
+        stdout.puts "Sweep complete:"
+        stdout.puts "  Elapsed: #{stats[:elapsed_seconds].round(2)}s"
+        stdout.puts "  Budget honored: #{stats[:budget_honored]}"
+
+        Hook::ExitCodes::SUCCESS
+      end
+
+      def hook_publish(handler, payload)
+        result = handler.publish(payload)
+
+        case result[:status]
+        when :updated
+          stdout.puts "Published snapshot to #{result[:path]}"
+        when :unchanged
+          stdout.puts "No changes - #{result[:path]} is up to date"
+        end
+
+        Hook::ExitCodes::SUCCESS
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/ingest_command.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Ingests transcript delta into memory database
+    class IngestCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {source: "claude_code", db: ClaudeMemory.project_db_path}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory ingest [options]"
+            parser.on("--source SOURCE", "Source identifier (default: claude_code)") { |v| o[:source] = v }
+            parser.on("--session-id ID", "Session identifier (required)") { |v| o[:session_id] = v }
+            parser.on("--transcript-path PATH", "Path to transcript file (required)") { |v| o[:transcript_path] = v }
+            parser.on("--db PATH", "Database path") { |v| o[:db] = v }
+          end
+        end
+
+        unless opts && opts[:session_id] && opts[:transcript_path]
+          stderr.puts "\nError: --session-id and --transcript-path are required"
+          return 1
+        end
+
+        store = ClaudeMemory::Store::SQLiteStore.new(opts[:db])
+        ingester = ClaudeMemory::Ingest::Ingester.new(store)
+
+        result = ingester.ingest(
+          source: opts[:source],
+          session_id: opts[:session_id],
+          transcript_path: opts[:transcript_path]
+        )
+
+        case result[:status]
+        when :ingested
+          stdout.puts "Ingested #{result[:bytes_read]} bytes (content_id: #{result[:content_id]})"
+        when :no_change
+          stdout.puts "No new content to ingest"
+        end
+
+        store.close
+        0
+      rescue ClaudeMemory::Ingest::TranscriptReader::FileNotFoundError => e
+        stderr.puts "Error: #{e.message}"
+        1
+      end
+    end
+  end
+end