claude_memory 0.1.0 → 0.2.0

data/lib/claude_memory/commands/init_command.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # Initializes ClaudeMemory in a project or globally
+    class InitCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {global: false}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--global", "Install to global ~/.claude/ settings") { o[:global] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        if opts[:global]
+          init_global
+        else
+          init_local
+        end
+      end
+
+      private
+
+      def init_local
+        stdout.puts "Initializing ClaudeMemory (project-local)...\n\n"
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        manager.ensure_global!
+        stdout.puts "✓ Global database: #{manager.global_db_path}"
+        manager.ensure_project!
+        stdout.puts "✓ Project database: #{manager.project_db_path}"
+        manager.close
+
+        FileUtils.mkdir_p(".claude/rules")
+        stdout.puts "✓ Created .claude/rules directory"
+
+        configure_project_hooks
+        configure_project_mcp
+        install_output_style
+
+        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"
+
+        0
+      end
+
+      def init_global
+        stdout.puts "Initializing ClaudeMemory (global only)...\n\n"
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        manager.ensure_global!
+        stdout.puts "✓ Created global database: #{manager.global_db_path}"
+        manager.close
+
+        configure_global_hooks
+        configure_global_mcp
+        configure_global_memory
+
+        stdout.puts "\n=== Global Setup Complete ===\n"
+        stdout.puts "ClaudeMemory is now configured globally."
+        stdout.puts "\nNote: Run 'claude-memory init' in each project for project-specific memory."
+
+        0
+      end
+
+      def configure_global_hooks
+        settings_path = File.join(Dir.home, ".claude", "settings.json")
+        FileUtils.mkdir_p(File.dirname(settings_path))
+
+        db_path = ClaudeMemory.global_db_path
+        ingest_cmd = "claude-memory hook ingest --db #{db_path}"
+        sweep_cmd = "claude-memory hook sweep --db #{db_path}"
+
+        hooks_config = build_hooks_config(ingest_cmd, sweep_cmd)
+
+        existing = load_json_file(settings_path)
+        existing["hooks"] ||= {}
+        existing["hooks"].merge!(hooks_config["hooks"])
+
+        File.write(settings_path, JSON.pretty_generate(existing))
+        stdout.puts "✓ Configured hooks in #{settings_path}"
+      end
+
+      def configure_global_mcp
+        mcp_path = File.join(Dir.home, ".claude.json")
+
+        existing = load_json_file(mcp_path)
+        existing["mcpServers"] ||= {}
+        existing["mcpServers"]["claude-memory"] = {
+          "type" => "stdio",
+          "command" => "claude-memory",
+          "args" => ["serve-mcp"]
+        }
+
+        File.write(mcp_path, JSON.pretty_generate(existing))
+        stdout.puts "✓ Configured MCP server in #{mcp_path}"
+      end
+
+      def configure_global_memory
+        global_claude_dir = File.join(Dir.home, ".claude")
+        claude_md_path = File.join(global_claude_dir, "CLAUDE.md")
+
+        memory_instruction = <<~MD
+          # ClaudeMemory
+
+          ClaudeMemory is installed globally. Use these MCP tools:
+          - `memory.recall` - Search for relevant facts
+          - `memory.explain` - Get detailed fact provenance
+          - `memory.conflicts` - Show open contradictions
+          - `memory.status` - Check system health
+        MD
+
+        FileUtils.mkdir_p(global_claude_dir)
+        if File.exist?(claude_md_path)
+          content = File.read(claude_md_path)
+          unless content.include?("ClaudeMemory")
+            File.write(claude_md_path, content + "\n\n" + memory_instruction)
+          end
+        else
+          File.write(claude_md_path, memory_instruction)
+        end
+
+        stdout.puts "✓ Updated #{claude_md_path}"
+      end
+
+      def configure_project_hooks
+        settings_path = ".claude/settings.json"
+        FileUtils.mkdir_p(File.dirname(settings_path))
+
+        db_path = ClaudeMemory.project_db_path
+        ingest_cmd = "claude-memory hook ingest --db #{db_path}"
+        sweep_cmd = "claude-memory hook sweep --db #{db_path}"
+
+        hooks_config = build_hooks_config(ingest_cmd, sweep_cmd)
+
+        existing = load_json_file(settings_path)
+        existing["hooks"] ||= {}
+        existing["hooks"].merge!(hooks_config["hooks"])
+
+        File.write(settings_path, JSON.pretty_generate(existing))
+        stdout.puts "✓ Configured hooks in #{settings_path}"
+      end
+
+      def configure_project_mcp
+        mcp_path = ".claude.json"
+
+        existing = load_json_file(mcp_path)
+        existing["mcpServers"] ||= {}
+        existing["mcpServers"]["claude-memory"] = {
+          "type" => "stdio",
+          "command" => "claude-memory",
+          "args" => ["serve-mcp"]
+        }
+
+        File.write(mcp_path, JSON.pretty_generate(existing))
+        stdout.puts "✓ Configured MCP server in #{mcp_path}"
+      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 build_hooks_config(ingest_cmd, sweep_cmd)
+        {
+          "hooks" => {
+            "Stop" => [{
+              "hooks" => [
+                {"type" => "command", "command" => ingest_cmd, "timeout" => 10}
+              ]
+            }],
+            "SessionStart" => [{
+              "hooks" => [
+                {"type" => "command", "command" => ingest_cmd, "timeout" => 10}
+              ]
+            }],
+            "PreCompact" => [{
+              "hooks" => [
+                {"type" => "command", "command" => ingest_cmd, "timeout" => 30},
+                {"type" => "command", "command" => sweep_cmd, "timeout" => 30}
+              ]
+            }],
+            "SessionEnd" => [{
+              "hooks" => [
+                {"type" => "command", "command" => ingest_cmd, "timeout" => 30},
+                {"type" => "command", "command" => sweep_cmd, "timeout" => 30}
+              ]
+            }]
+          }
+        }
+      end
+
+      def load_json_file(path)
+        return {} unless File.exist?(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/promote_command.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Promotes a project fact to global memory
+    class PromoteCommand < BaseCommand
+      def call(args)
+        fact_id = args.first&.to_i
+        unless fact_id && fact_id > 0
+          stderr.puts "Usage: claude-memory promote <fact_id>"
+          stderr.puts "\nPromotes a project fact to the global database."
+          return 1
+        end
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        global_fact_id = manager.promote_fact(fact_id)
+
+        if global_fact_id
+          stdout.puts "Promoted fact ##{fact_id} to global database as fact ##{global_fact_id}"
+          manager.close
+          0
+        else
+          stderr.puts "Fact ##{fact_id} not found in project database."
+          manager.close
+          1
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/publish_command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Publishes memory snapshot to Claude Code
+    class PublishCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {mode: :shared, granularity: :repo, since: nil, scope: "project"}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--mode MODE", "Mode: shared, local, or home") { |v| o[:mode] = v.to_sym }
+            parser.on("--granularity LEVEL", "Granularity: repo, paths, or nested") { |v| o[:granularity] = v.to_sym }
+            parser.on("--since ISO", "Include changes since timestamp") { |v| o[:since] = v }
+            parser.on("--scope SCOPE", "Scope: project or global") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+        publish = ClaudeMemory::Publish.new(store)
+
+        result = publish.publish!(mode: opts[:mode], granularity: opts[:granularity], since: opts[:since])
+
+        case result[:status]
+        when :updated
+          stdout.puts "Published #{opts[:scope]} snapshot to #{result[:path]}"
+        when :unchanged
+          stdout.puts "No changes - #{result[:path]} is up to date"
+        end
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/recall_command.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Recalls facts matching a query
+    class RecallCommand < BaseCommand
+      def call(args)
+        query = args.first
+        unless query
+          stderr.puts "Usage: claude-memory recall <query> [--limit N] [--scope project|global|all]"
+          return 1
+        end
+
+        opts = parse_options(args[1..] || [], {limit: 10, scope: "all"}) do |o|
+          OptionParser.new do |parser|
+            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?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        recall = ClaudeMemory::Recall.new(manager)
+
+        results = recall.query(query, limit: opts[:limit], scope: opts[:scope])
+        if results.empty?
+          stdout.puts "No facts found."
+        else
+          stdout.puts "Found #{results.size} fact(s):\n\n"
+          results.each do |result|
+            print_fact(result[:fact], source: result[:source])
+            print_receipts(result[:receipts])
+            stdout.puts
+          end
+        end
+
+        manager.close
+        0
+      end
+
+      private
+
+      def print_fact(fact, source: nil)
+        source_label = source ? " [#{source}]" : ""
+        stdout.puts "  #{fact[:subject_name]}.#{fact[:predicate]} = #{fact[:object_literal]}#{source_label}"
+        stdout.puts "    Status: #{fact[:status]}, Confidence: #{fact[:confidence]}"
+        stdout.puts "    Valid: #{fact[:valid_from]} - #{fact[:valid_to] || "present"}"
+      end
+
+      def print_receipts(receipts)
+        return if receipts.empty?
+
+        stdout.puts "  Receipts:"
+        receipts.each do |r|
+          quote_preview = r[:quote]&.slice(0, 80)&.gsub(/\s+/, " ")
+          stdout.puts "    - [#{r[:strength]}] \"#{quote_preview}...\""
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Registry for CLI command lookup and dispatch
+    # Maps command names to command classes for dynamic dispatch
+    class Registry
+      # Map of command names to class names
+      # As more commands are extracted, add them here
+      COMMANDS = {
+        "help" => "HelpCommand",
+        "version" => "VersionCommand",
+        "doctor" => "DoctorCommand",
+        "promote" => "PromoteCommand",
+        "search" => "SearchCommand",
+        "explain" => "ExplainCommand",
+        "conflicts" => "ConflictsCommand",
+        "changes" => "ChangesCommand",
+        "recall" => "RecallCommand",
+        "sweep" => "SweepCommand",
+        "ingest" => "IngestCommand",
+        "publish" => "PublishCommand",
+        "db:init" => "DbInitCommand",
+        "init" => "InitCommand",
+        "serve-mcp" => "ServeMcpCommand",
+        "hook" => "HookCommand"
+      }.freeze
+
+      # Find a command class by name
+      # @param command_name [String] the command name (e.g., "help", "version")
+      # @return [Class, nil] the command class, or nil if not found
+      def self.find(command_name)
+        return nil if command_name.nil?
+
+        class_name = COMMANDS[command_name]
+        return nil unless class_name
+
+        Commands.const_get(class_name)
+      end
+
+      # Get all registered command names
+      # @return [Array<String>] list of command names
+      def self.all_commands
+        COMMANDS.keys
+      end
+
+      # Check if a command is registered
+      # @param command_name [String] the command name
+      # @return [Boolean] true if registered
+      def self.registered?(command_name)
+        COMMANDS.key?(command_name)
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/search_command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Searches indexed content using full-text search
+    class SearchCommand < BaseCommand
+      def call(args)
+        query = args.first
+        unless query
+          stderr.puts "Usage: claude-memory search <query> [--db PATH] [--limit N]"
+          return 1
+        end
+
+        opts = parse_options(args[1..] || [], {limit: 10, scope: "all"}) do |o|
+          OptionParser.new do |parser|
+            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?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope((opts[:scope] == "global") ? "global" : "project")
+        fts = ClaudeMemory::Index::LexicalFTS.new(store)
+
+        ids = fts.search(query, limit: opts[:limit])
+        if ids.empty?
+          stdout.puts "No results found."
+        else
+          stdout.puts "Found #{ids.size} result(s):"
+          ids.each do |id|
+            text = store.content_items.where(id: id).get(:raw_text)
+            preview = text&.slice(0, 100)&.gsub(/\s+/, " ")
+            stdout.puts "  [#{id}] #{preview}..."
+          end
+        end
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/serve_mcp_command.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Starts MCP server
+    class ServeMcpCommand < BaseCommand
+      def call(_args)
+        manager = ClaudeMemory::Store::StoreManager.new
+        server = ClaudeMemory::MCP::Server.new(manager)
+        server.run
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/sweep_command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Runs maintenance and pruning on memory database
+    class SweepCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {budget: 5, scope: "project"}) do |o|
+          OptionParser.new do |parser|
+            parser.on("--budget SECONDS", Integer, "Time budget in seconds") { |v| o[:budget] = v }
+            parser.on("--scope SCOPE", "Scope: project or global") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+        sweeper = ClaudeMemory::Sweep::Sweeper.new(store)
+
+        stdout.puts "Running sweep on #{opts[:scope]} database with #{opts[:budget]}s budget..."
+        stats = sweeper.run!(budget_seconds: opts[:budget])
+
+        stdout.puts "Sweep complete:"
+        stdout.puts "  Proposed facts expired: #{stats[:proposed_facts_expired]}"
+        stdout.puts "  Disputed facts expired: #{stats[:disputed_facts_expired]}"
+        stdout.puts "  Orphaned provenance deleted: #{stats[:orphaned_provenance_deleted]}"
+        stdout.puts "  Old content pruned: #{stats[:old_content_pruned]}"
+        stdout.puts "  Elapsed: #{stats[:elapsed_seconds].round(2)}s"
+        stdout.puts "  Budget honored: #{stats[:budget_honored]}"
+
+        manager.close
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/version_command.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Displays version information for claude-memory
+    class VersionCommand < BaseCommand
+      def call(_args)
+        stdout.puts "claude-memory #{ClaudeMemory::VERSION}"
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  # Centralized configuration and ENV access
+  # Provides consistent access to paths and environment variables
+  class Configuration
+    attr_reader :env
+
+    def initialize(env = ENV)
+      @env = env
+    end
+
+    def home_dir
+      env["HOME"] || File.expand_path("~")
+    end
+
+    def project_dir
+      env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+    end
+
+    def global_db_path
+      File.join(home_dir, ".claude", "memory.sqlite3")
+    end
+
+    def project_db_path(project_path = nil)
+      path = project_path || project_dir
+      File.join(path, ".claude", "memory.sqlite3")
+    end
+
+    def session_id
+      env["CLAUDE_SESSION_ID"]
+    end
+
+    def transcript_path
+      env["CLAUDE_TRANSCRIPT_PATH"]
+    end
+  end
+end

data/lib/claude_memory/core/fact_id.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Value object representing a fact identifier
+    # Provides type safety and validation for fact IDs (positive integers)
+    class FactId
+      attr_reader :value
+
+      def initialize(value)
+        @value = value.to_i
+        validate!
+        freeze
+      end
+
+      def to_i
+        value
+      end
+
+      def to_s
+        value.to_s
+      end
+
+      def ==(other)
+        other.is_a?(FactId) && other.value == value
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        value.hash
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "Fact ID must be a positive integer" unless value.positive?
+      end
+    end
+  end
+end

data/lib/claude_memory/core/null_explanation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Null object pattern for Explanation
+    # Represents a non-existent explanation without using nil
+    class NullExplanation
+      def present?
+        false
+      end
+
+      def fact
+        NullFact.new
+      end
+
+      def receipts
+        []
+      end
+
+      def superseded_by
+        []
+      end
+
+      def supersedes
+        []
+      end
+
+      def conflicts
+        []
+      end
+
+      def to_h
+        {
+          fact: fact.to_h,
+          receipts: receipts,
+          superseded_by: superseded_by,
+          supersedes: supersedes,
+          conflicts: conflicts
+        }
+      end
+
+      def [](key)
+        to_h[key]
+      end
+    end
+  end
+end

data/lib/claude_memory/core/null_fact.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Core
+    # Null object pattern for Fact
+    # Represents a non-existent fact without using nil
+    class NullFact
+      def present?
+        false
+      end
+
+      def to_h
+        {
+          id: nil,
+          subject_name: nil,
+          predicate: nil,
+          object_literal: nil,
+          status: "not_found",
+          confidence: 0.0,
+          valid_from: nil,
+          valid_to: nil
+        }
+      end
+
+      def [](key)
+        to_h[key]
+      end
+    end
+  end
+end