swarm_memory 2.1.4 → 2.1.6

data/lib/swarm_sdk/tools/stores/scratchpad_storage.rb

@@ -1,272 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Stores
-      # ScratchpadStorage provides volatile, shared storage
-      #
-      # Features:
-      # - Shared: All agents share the same scratchpad
-      # - Volatile: NEVER persists - all data lost when process ends
-      # - Path-based: Hierarchical organization using file-path-like addresses
-      # - Metadata-rich: Stores content + title + timestamp + size
-      # - Thread-safe: Mutex-protected operations
-      #
-      # Use for temporary, cross-agent communication within a single session.
-      class ScratchpadStorage < Storage
-        # Initialize scratchpad storage (always volatile)
-        #
-        # @param total_size_limit [Integer, nil] Maximum total size in bytes (defaults to Defaults::Storage::TOTAL_SIZE_BYTES)
-        def initialize(total_size_limit: nil)
-          super() # Initialize parent Storage class
-          @entries = {}
-          @total_size = 0
-          @total_size_limit = total_size_limit || Defaults::Storage::TOTAL_SIZE_BYTES
-          @mutex = Mutex.new
-        end
-
-        # Write content to scratchpad
-        #
-        # @param file_path [String] Path to store content
-        # @param content [String] Content to store
-        # @param title [String] Brief title describing the content
-        # @raise [ArgumentError] If size limits are exceeded
-        # @return [Entry] The created entry
-        def write(file_path:, content:, title:)
-          @mutex.synchronize do
-            raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
-            raise ArgumentError, "content is required" if content.nil?
-            raise ArgumentError, "title is required" if title.nil? || title.to_s.strip.empty?
-
-            content_size = content.bytesize
-
-            # Check entry size limit
-            if content_size > Defaults::Storage::ENTRY_SIZE_BYTES
-              raise ArgumentError, "Content exceeds maximum size (#{format_bytes(Defaults::Storage::ENTRY_SIZE_BYTES)}). " \
-                "Current: #{format_bytes(content_size)}"
-            end
-
-            # Calculate new total size
-            existing_entry = @entries[file_path]
-            existing_size = existing_entry ? existing_entry.size : 0
-            new_total_size = @total_size - existing_size + content_size
-
-            # Check total size limit
-            if new_total_size > @total_size_limit
-              raise ArgumentError, "Scratchpad full (#{format_bytes(@total_size_limit)} limit). " \
-                "Current: #{format_bytes(@total_size)}, " \
-                "Would be: #{format_bytes(new_total_size)}. " \
-                "Clear old entries or use smaller content."
-            end
-
-            # Create entry
-            entry = Entry.new(
-              content: content,
-              title: title,
-              updated_at: Time.now,
-              size: content_size,
-            )
-
-            # Update storage
-            @entries[file_path] = entry
-            @total_size = new_total_size
-
-            entry
-          end
-        end
-
-        # Read content from scratchpad
-        #
-        # @param file_path [String] Path to read from
-        # @raise [ArgumentError] If path not found
-        # @return [String] Content at the path
-        def read(file_path:)
-          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
-
-          entry = @entries[file_path]
-          raise ArgumentError, "scratchpad://#{file_path} not found" unless entry
-
-          entry.content
-        end
-
-        # Delete a specific entry
-        #
-        # @param file_path [String] Path to delete
-        # @raise [ArgumentError] If path not found
-        # @return [void]
-        def delete(file_path:)
-          @mutex.synchronize do
-            raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
-
-            entry = @entries[file_path]
-            raise ArgumentError, "scratchpad://#{file_path} not found" unless entry
-
-            # Update total size
-            @total_size -= entry.size
-
-            # Remove entry
-            @entries.delete(file_path)
-          end
-        end
-
-        # List scratchpad entries, optionally filtered by prefix
-        #
-        # @param prefix [String, nil] Filter by path prefix
-        # @return [Array<Hash>] Array of entry metadata (path, title, size, updated_at)
-        def list(prefix: nil)
-          entries = @entries
-
-          # Filter by prefix if provided
-          if prefix && !prefix.empty?
-            entries = entries.select { |path, _| path.start_with?(prefix) }
-          end
-
-          # Return metadata sorted by path
-          entries.map do |path, entry|
-            {
-              path: path,
-              title: entry.title,
-              size: entry.size,
-              updated_at: entry.updated_at,
-            }
-          end.sort_by { |e| e[:path] }
-        end
-
-        # Search entries by glob pattern
-        #
-        # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
-        # @return [Array<Hash>] Array of matching entry metadata, sorted by most recent first
-        def glob(pattern:)
-          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
-
-          # Convert glob pattern to regex
-          regex = glob_to_regex(pattern)
-
-          # Filter entries by pattern
-          matching_entries = @entries.select { |path, _| regex.match?(path) }
-
-          # Return metadata sorted by most recent first
-          matching_entries.map do |path, entry|
-            {
-              path: path,
-              title: entry.title,
-              size: entry.size,
-              updated_at: entry.updated_at,
-            }
-          end.sort_by { |e| -e[:updated_at].to_f }
-        end
-
-        # Search entry content by pattern
-        #
-        # @param pattern [String] Regular expression pattern to search for
-        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
-        # @param output_mode [String] Output mode: "files_with_matches" (default), "content", or "count"
-        # @return [Array<Hash>, String] Results based on output_mode
-        def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
-          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
-
-          # Create regex from pattern
-          flags = case_insensitive ? Regexp::IGNORECASE : 0
-          regex = Regexp.new(pattern, flags)
-
-          case output_mode
-          when "files_with_matches"
-            # Return just the paths that match
-            matching_paths = @entries.select { |_path, entry| regex.match?(entry.content) }
-              .map { |path, _| path }
-              .sort
-            matching_paths
-          when "content"
-            # Return paths with matching lines, sorted by most recent first
-            results = []
-            @entries.each do |path, entry|
-              matching_lines = []
-              entry.content.each_line.with_index(1) do |line, line_num|
-                matching_lines << { line_number: line_num, content: line.chomp } if regex.match?(line)
-              end
-              results << { path: path, matches: matching_lines, updated_at: entry.updated_at } unless matching_lines.empty?
-            end
-            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
-          when "count"
-            # Return paths with match counts, sorted by most recent first
-            results = []
-            @entries.each do |path, entry|
-              count = entry.content.scan(regex).size
-              results << { path: path, count: count, updated_at: entry.updated_at } if count > 0
-            end
-            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
-          else
-            raise ArgumentError, "Invalid output_mode: #{output_mode}. Must be 'files_with_matches', 'content', or 'count'"
-          end
-        end
-
-        # Clear all entries
-        #
-        # @return [void]
-        def clear
-          @mutex.synchronize do
-            @entries.clear
-            @total_size = 0
-          end
-        end
-
-        # Get current total size
-        #
-        # @return [Integer] Total size in bytes
-        attr_reader :total_size
-
-        # Get number of entries
-        #
-        # @return [Integer] Number of entries
-        def size
-          @entries.size
-        end
-
-        # Get all entries with content for snapshot
-        #
-        # Thread-safe method that returns a copy of all entries.
-        # Used by snapshot/restore functionality.
-        #
-        # @return [Hash] { path => Entry }
-        def all_entries
-          @mutex.synchronize do
-            @entries.dup
-          end
-        end
-
-        # Restore entries from snapshot
-        #
-        # Restores entries directly without using write() to preserve timestamps.
-        # This ensures entry ordering and metadata accuracy after restore.
-        #
-        # @param entries_data [Hash] { path => { content:, title:, updated_at:, size: } }
-        # @return [void]
-        def restore_entries(entries_data)
-          @mutex.synchronize do
-            entries_data.each do |path, data|
-              # Handle both symbol and string keys from JSON
-              content = data[:content] || data["content"]
-              title = data[:title] || data["title"]
-              updated_at_str = data[:updated_at] || data["updated_at"]
-
-              # Parse timestamp from ISO8601 string
-              updated_at = Time.parse(updated_at_str)
-
-              # Create entry with preserved timestamp
-              entry = Entry.new(
-                content: content,
-                title: title,
-                updated_at: updated_at,
-                size: content.bytesize,
-              )
-
-              # Update storage
-              @entries[path] = entry
-              @total_size += entry.size
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/stores/storage.rb

@@ -1,142 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Stores
-      # Abstract base class for hierarchical key-value storage with metadata
-      #
-      # Provides session-scoped storage for agents with path-based organization.
-      # Subclasses implement persistence behavior (volatile vs persistent).
-      #
-      # Features:
-      # - Path-based: Hierarchical organization using file-path-like addresses
-      # - Metadata-rich: Stores content + title + timestamp + size
-      # - Search capabilities: Glob patterns and grep-style content search
-      # - Thread-safe: Mutex-protected operations
-      class Storage
-        # Represents a single storage entry with metadata
-        Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)
-
-        # Initialize storage
-        #
-        # Subclasses should call super() in their initialize method.
-        # This base implementation does nothing - it exists only to satisfy RuboCop.
-        def initialize
-          # Base class initialization - subclasses implement their own logic
-        end
-
-        # Write content to storage
-        #
-        # @param file_path [String] Path to store content
-        # @param content [String] Content to store
-        # @param title [String] Brief title describing the content
-        # @raise [ArgumentError] If size limits are exceeded
-        # @return [Entry] The created entry
-        def write(file_path:, content:, title:)
-          raise NotImplementedError, "Subclass must implement #write"
-        end
-
-        # Read content from storage
-        #
-        # @param file_path [String] Path to read from
-        # @raise [ArgumentError] If path not found
-        # @return [String] Content at the path
-        def read(file_path:)
-          raise NotImplementedError, "Subclass must implement #read"
-        end
-
-        # Delete a specific entry
-        #
-        # @param file_path [String] Path to delete
-        # @raise [ArgumentError] If path not found
-        # @return [void]
-        def delete(file_path:)
-          raise NotImplementedError, "Subclass must implement #delete"
-        end
-
-        # List entries, optionally filtered by prefix
-        #
-        # @param prefix [String, nil] Filter by path prefix
-        # @return [Array<Hash>] Array of entry metadata (path, title, size, updated_at)
-        def list(prefix: nil)
-          raise NotImplementedError, "Subclass must implement #list"
-        end
-
-        # Search entries by glob pattern
-        #
-        # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
-        # @return [Array<Hash>] Array of matching entry metadata, sorted by most recent first
-        def glob(pattern:)
-          raise NotImplementedError, "Subclass must implement #glob"
-        end
-
-        # Search entry content by pattern
-        #
-        # @param pattern [String] Regular expression pattern to search for
-        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
-        # @param output_mode [String] Output mode: "files_with_matches" (default), "content", or "count"
-        # @return [Array<Hash>, String] Results based on output_mode
-        def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
-          raise NotImplementedError, "Subclass must implement #grep"
-        end
-
-        # Clear all entries
-        #
-        # @return [void]
-        def clear
-          raise NotImplementedError, "Subclass must implement #clear"
-        end
-
-        # Get current total size
-        #
-        # @return [Integer] Total size in bytes
-        def total_size
-          raise NotImplementedError, "Subclass must implement #total_size"
-        end
-
-        # Get number of entries
-        #
-        # @return [Integer] Number of entries
-        def size
-          raise NotImplementedError, "Subclass must implement #size"
-        end
-
-        protected
-
-        # Format bytes to human-readable size
-        #
-        # @param bytes [Integer] Number of bytes
-        # @return [String] Formatted size (e.g., "1.5MB", "500.0KB")
-        def format_bytes(bytes)
-          if bytes >= 1_000_000
-            "#{(bytes.to_f / 1_000_000).round(1)}MB"
-          elsif bytes >= 1_000
-            "#{(bytes.to_f / 1_000).round(1)}KB"
-          else
-            "#{bytes}B"
-          end
-        end
-
-        # Convert glob pattern to regex
-        #
-        # @param pattern [String] Glob pattern
-        # @return [Regexp] Regular expression
-        def glob_to_regex(pattern)
-          # Escape special regex characters except glob wildcards
-          escaped = Regexp.escape(pattern)
-
-          # Convert glob wildcards to regex
-          # ** matches any number of directories (including zero)
-          escaped = escaped.gsub('\*\*', ".*")
-          # * matches anything except directory separator
-          escaped = escaped.gsub('\*', "[^/]*")
-          # ? matches single character except directory separator
-          escaped = escaped.gsub('\?', "[^/]")
-
-          # Anchor to start and end
-          Regexp.new("\\A#{escaped}\\z")
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/stores/todo_manager.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module Stores
-      # TodoManager provides per-agent todo list storage
-      #
-      # Each agent maintains its own independent todo list that persists
-      # throughout the agent's execution session. This allows agents to
-      # track progress on complex multi-step tasks.
-      class TodoManager
-        @storage = {}
-        @mutex = Mutex.new
-
-        class << self
-          # Get the current todo list for an agent
-          #
-          # @param agent_id [Symbol, String] Unique agent identifier
-          # @return [Array<Hash>] Array of todo items
-          def get_todos(agent_id)
-            @mutex.synchronize do
-              @storage[agent_id.to_sym] ||= []
-            end
-          end
-
-          # Set the todo list for an agent
-          #
-          # @param agent_id [Symbol, String] Unique agent identifier
-          # @param todos [Array<Hash>] Array of todo items
-          # @return [Array<Hash>] The stored todos
-          def set_todos(agent_id, todos)
-            @mutex.synchronize do
-              @storage[agent_id.to_sym] = todos
-            end
-          end
-
-          # Clear all todos for an agent
-          #
-          # @param agent_id [Symbol, String] Unique agent identifier
-          def clear_todos(agent_id)
-            @mutex.synchronize do
-              @storage.delete(agent_id.to_sym)
-            end
-          end
-
-          # Clear all todos for all agents
-          def clear_all
-            @mutex.synchronize do
-              @storage.clear
-            end
-          end
-
-          # Get summary of all agent todo lists
-          #
-          # @return [Hash] Map of agent_id => todo count
-          def summary
-            @mutex.synchronize do
-              @storage.transform_values(&:size)
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/think.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Think tool for explicit reasoning and planning
-    #
-    # Allows the agent to write down thoughts, plans, strategies, and intermediate
-    # calculations. These thoughts become part of the conversation context, enabling
-    # better attention and reasoning through complex problems.
-    #
-    # This is inspired by research showing that explicitly articulating reasoning steps
-    # (chain-of-thought prompting) leads to significantly better outcomes, especially
-    # for complex tasks requiring multi-step reasoning or arithmetic.
-    class Think < RubyLLM::Tool
-      def name
-        "Think"
-      end
-
-      description <<~DESC
-        **IMPORTANT: You SHOULD use this tool frequently throughout your work. Using this tool leads to significantly
-        better outcomes and more accurate solutions. Make it a habit to think before acting.**
-
-        This tool allows you to write down your thoughts, plans, strategies, and intermediate calculations.
-        Think of it as your working memory - just as humans think before speaking or acting, you should think before
-        using other tools or providing responses.
-
-        **STRONGLY RECOMMENDED to use this tool:**
-        - **ALWAYS** before starting any task (even simple ones)
-        - **ALWAYS** when you need to do any arithmetic or counting
-        - **ALWAYS** after reading files or getting search results to process what you learned
-        - **FREQUENTLY** between steps to track progress and plan next actions
-
-        This is your private thinking space - use it liberally to enhance your problem-solving capabilities. Recording
-        your thoughts helps you maintain context across multiple steps and remember important information throughout your task.
-
-        When and how to use this tool:
-
-        1. **Before starting any complex task**: Write down your understanding of the problem, break it into smaller
-           sub-tasks, and create a step-by-step plan. Example:
-           - "The user wants me to refactor this codebase. Let me first understand the structure..."
-           - "I need to: 1) Analyze current architecture, 2) Identify pain points, 3) Propose changes..."
-
-        2. **For arithmetic and calculations**: Work through math problems step by step. Example:
-           - "If we have 150 requests/second and each takes 20ms, that's 150 * 0.02 = 3 seconds of CPU time..."
-           - "Converting 2GB to bytes: 2 * 1024 * 1024 * 1024 = 2,147,483,648 bytes"
-
-        3. **After completing sub-tasks**: Summarize what you've accomplished and what remains. Example:
-           - "I've successfully implemented the authentication module. Next, I need to integrate it with the API..."
-           - "Fixed 3 out of 5 bugs. Remaining: memory leak in parser, race condition in worker thread"
-
-        4. **When encountering complexity**: Break down complex logic or decisions. Example:
-           - "This function has multiple edge cases. Let me list them: null input, empty array, negative numbers..."
-           - "The user's request is ambiguous. Possible interpretations: A) modify existing code, B) create new module..."
-
-        5. **For remembering context**: Store important information you'll need later. Example:
-           - "Important: The user mentioned they're using Ruby 3.2, so I can use pattern matching"
-           - "File structure: main.rb requires from lib/, config is in config.yml"
-
-        6. **When debugging or analyzing**: Track your investigation process. Example:
-           - "The error occurs in line 42. Let me trace backwards: function called from main(), receives data from..."
-           - "Hypothesis: the bug might be due to timezone differences. Let me check..."
-
-        7. **For creative problem-solving**: Brainstorm multiple approaches before choosing one. Example:
-           - "Approaches to optimize this: 1) Add caching, 2) Use parallel processing, 3) Optimize algorithm..."
-           - "Design patterns that could work here: Factory, Observer, or maybe Strategy pattern..."
-
-        **Remember: The most successful agents use this tool 5-10 times per task on average. If you haven't used this
-        tool in the last 2-3 actions, you probably should. Using this tool is a sign of thoughtful, methodical problem
-        solving and leads to fewer mistakes and better solutions.**
-
-        Your thoughts persist throughout your session as part of the conversation history, so you can refer
-        back to earlier thinking. Use clear formatting and organization to make it easy to reference
-        later. Don't hesitate to think out loud - this tool is designed to augment your cognitive capabilities and help
-        you deliver better solutions.
-
-        **CRITICAL:** The Think tool takes only one parameter: thoughts. Do not include any other parameters.
-      DESC
-
-      param :thoughts,
-        type: "string",
-        desc: "Your thoughts, plans, calculations, or any notes you want to record",
-        required: true
-
-      def execute(**kwargs)
-        <<~RESP
-          Thought noted.
-        RESP
-        # <system-reminder>The user cannot see your thoughts. You MUST NOT stop without giving the user a response.</system-reminder>
-      end
-
-      private
-
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-    end
-  end
-end