claude_swarm 1.0.1 → 1.0.2

data/lib/swarm_memory/tools/memory_glob.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Tool for searching memory entries by glob pattern
+    #
+    # Finds memory entries matching a glob pattern (like filesystem glob).
+    # Each agent has its own isolated memory storage.
+    class MemoryGlob < RubyLLM::Tool
+      description <<~DESC
+        Search your memory entries using glob patterns (like filesystem glob).
+
+        REQUIRED: Provide the pattern parameter - the glob pattern to match entries against.
+
+        **Parameters:**
+        - pattern (REQUIRED): Glob pattern with wildcards (e.g., '**/*.txt', 'parallel/*/task_*', 'skill/**')
+
+        **Glob Pattern Syntax (Standard Ruby Glob):**
+        - `*` - matches .md files at a single directory level (e.g., 'fact/*' → fact/*.md)
+        - `**` - matches .md files recursively at any depth (e.g., 'fact/**' → fact/**/*.md)
+        - `?` - matches any single character (e.g., 'task_?')
+        - `[abc]` - matches any character in the set (e.g., 'task_[0-9]')
+
+        **Returns:**
+        List of matching .md memory entries with:
+        - Full memory:// path
+        - Entry title
+        - Size in bytes/KB/MB
+
+        **Note**: Only returns .md files (actual memory entries), not directory entries.
+
+        **MEMORY STRUCTURE (4 Fixed Categories Only):**
+        ALL patterns MUST target one of these 4 categories:
+        - concept/{domain}/** - Abstract ideas
+        - fact/{subfolder}/** - Concrete information
+        - skill/{domain}/** - Procedures
+        - experience/** - Lessons
+        INVALID: documentation/, reference/, parallel/, analysis/, tutorial/
+
+        **Common Use Cases:**
+        ```
+        # Find direct .md files in fact/
+        MemoryGlob(pattern: "fact/*")
+        Result: fact/api.md (only direct children, not nested)
+
+        # Find ALL facts recursively
+        MemoryGlob(pattern: "fact/**")
+        Result: fact/api.md, fact/people/john.md, fact/people/jane.md, ...
+
+        # Find all skills recursively
+        MemoryGlob(pattern: "skill/**")
+        Result: skill/debugging/api-errors.md, skill/meta/deep-learning.md, ...
+
+        # Find all concepts in a domain
+        MemoryGlob(pattern: "concept/ruby/**")
+        Result: concept/ruby/classes.md, concept/ruby/modules.md, ...
+
+        # Find direct files in fact/people/
+        MemoryGlob(pattern: "fact/people/*")
+        Result: fact/people/john.md, fact/people/jane.md (not fact/people/teams/x.md)
+
+        # Find all experiences
+        MemoryGlob(pattern: "experience/**")
+        Result: experience/fixed-cors-bug.md, experience/optimization.md, ...
+
+        # Find debugging skills recursively
+        MemoryGlob(pattern: "skill/debugging/**")
+        Result: skill/debugging/api-errors.md, skill/debugging/performance.md, ...
+
+        # Find all entries (all categories)
+        MemoryGlob(pattern: "**/*")
+        Result: All .md entries across all 4 categories
+        ```
+
+        **Understanding * vs **:**
+        - `fact/*` matches only direct .md files: fact/api.md
+        - `fact/**` matches ALL .md files recursively: fact/api.md, fact/people/john.md, ...
+        - To explore subdirectories, use recursive pattern and examine returned paths
+
+        **When to Use MemoryGlob:**
+        - Discovering what's in a memory hierarchy
+        - Finding all entries matching a naming convention
+        - Locating related entries by path pattern
+        - Exploring memory structure before reading specific entries
+        - Batch operations preparation (find all, then process each)
+
+        **Combining with Other Tools:**
+        1. Use MemoryGlob to find candidates
+        2. Use MemoryRead to examine specific entries
+        3. Use MemoryEdit/MemoryDelete to modify/remove them
+
+        **Tips:**
+        - Start with broad patterns and narrow down
+        - Use `**` for recursive searching entire hierarchies
+        - Combine with MemoryGrep if you need content-based search
+        - Check entry sizes to identify large entries
+      DESC
+
+      param :pattern,
+        desc: "Glob pattern - target concept/, fact/, skill/, or experience/ only (e.g., 'skill/**', 'concept/ruby/*', 'fact/people/*.md')",
+        required: true
+
+      # Initialize with storage instance
+      #
+      # @param storage [Core::Storage] Storage instance
+      def initialize(storage:)
+        super()
+        @storage = storage
+      end
+
+      # Override name to return simple "MemoryGlob"
+      def name
+        "MemoryGlob"
+      end
+
+      # Execute the tool
+      #
+      # @param pattern [String] Glob pattern to match
+      # @return [String] Formatted list of matching entries
+      def execute(pattern:)
+        entries = @storage.glob(pattern: pattern)
+
+        if entries.empty?
+          return "No entries found matching pattern '#{pattern}'"
+        end
+
+        result = []
+        result << "Memory entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
+
+        entries.each do |entry|
+          result << "  memory://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
+        end
+
+        result.join("\n")
+      rescue ArgumentError => e
+        validation_error(e.message)
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      # Format bytes to human-readable size
+      #
+      # @param bytes [Integer] Number of bytes
+      # @return [String] Formatted size
+      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
+    end
+  end
+end

data/lib/swarm_memory/tools/memory_grep.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Tool for searching memory content by pattern
+    #
+    # Searches content stored in memory entries using regex patterns.
+    # Each agent has its own isolated memory storage.
+    class MemoryGrep < RubyLLM::Tool
+      description <<~DESC
+        Search your memory content using regular expression patterns (like grep).
+
+        REQUIRED: Provide the pattern parameter - the regex pattern to search for in entry content.
+
+        MEMORY STRUCTURE: Searches across all 4 fixed categories (concept/, fact/, skill/, experience/)
+        NO OTHER top-level categories exist.
+
+        **Required Parameters:**
+        - pattern (REQUIRED): Regular expression pattern to search for (e.g., 'status: pending', 'TODO.*urgent', '\\btask_\\d+\\b')
+
+        **Optional Parameters:**
+        - path: Limit search to specific path (e.g., 'concept/', 'fact/api-design/', 'skill/ruby')
+        - case_insensitive: Set to true for case-insensitive search (default: false)
+        - output_mode: Choose output format - 'files_with_matches' (default), 'content', or 'count'
+
+        **Output Modes Explained:**
+        1. **files_with_matches** (default): Just shows which entries contain matches
+           - Fast and efficient for discovery
+           - Use when you want to know WHERE matches exist
+
+        2. **content**: Shows matching lines with line numbers
+           - See the actual matching content
+           - Use when you need to read the matches in context
+
+        3. **count**: Shows how many matches in each entry
+           - Quantify occurrences
+           - Use for statistics or finding entries with most matches
+
+        **Regular Expression Syntax:**
+        - Literal text: 'status: pending'
+        - Any character: 'task.done'
+        - Character classes: '[0-9]+' (digits), '[a-z]+' (lowercase)
+        - Word boundaries: '\\btodo\\b' (exact word)
+        - Anchors: '^Start' (line start), 'end$' (line end)
+        - Quantifiers: '*' (0+), '+' (1+), '?' (0 or 1), '{3}' (exactly 3)
+        - Alternation: 'pending|in-progress|blocked'
+
+        **Path Parameter - Directory-Style Filtering:**
+        The path parameter works just like searching in directories:
+        - 'concept/' - Search only concept entries
+        - 'fact/api-design' - Search only in fact/api-design (treats as directory)
+        - 'fact/api-design/' - Same as above
+        - 'skill/ruby/blocks.md' - Search only that specific file
+
+        **Examples:**
+        ```
+        # Find entries containing "TODO" (case-sensitive)
+        MemoryGrep(pattern: "TODO")
+
+        # Search only in concepts
+        MemoryGrep(pattern: "TODO", path: "concept/")
+
+        # Search in a specific subdirectory
+        MemoryGrep(pattern: "endpoint", path: "fact/api-design")
+
+        # Search a specific file
+        MemoryGrep(pattern: "lambda", path: "skill/ruby/blocks.md")
+
+        # Find entries with any status (case-insensitive)
+        MemoryGrep(pattern: "status:", case_insensitive: true)
+
+        # Show actual content of matches in skills only
+        MemoryGrep(pattern: "error|warning|failed", path: "skill/", output_mode: "content")
+
+        # Count how many times "completed" appears in experiences
+        MemoryGrep(pattern: "completed", path: "experience/", output_mode: "count")
+
+        # Find task numbers in facts
+        MemoryGrep(pattern: "task_\\d+", path: "fact/")
+
+        # Find incomplete tasks
+        MemoryGrep(pattern: "^- \\[ \\]", output_mode: "content")
+
+        # Find entries mentioning specific functions
+        MemoryGrep(pattern: "\\bprocess_data\\(")
+        ```
+
+        **Use Cases:**
+        - Finding entries by keyword or phrase
+        - Locating TODO items or action items
+        - Searching for error messages or debugging info
+        - Finding entries about specific code/functions
+        - Identifying patterns in your memory
+        - Content-based discovery (vs MemoryGlob's path-based discovery)
+
+        **Combining with Other Tools:**
+        1. Use MemoryGrep to find entries containing specific content
+        2. Use MemoryRead to examine full entries
+        3. Use MemoryEdit to update the found content
+
+        **Tips:**
+        - Start with simple literal patterns before using complex regex
+        - Use case_insensitive=true for broader matches
+        - Use path parameter to limit search scope (faster and more precise)
+        - Use output_mode="content" to see context around matches
+        - Escape special regex characters with backslash: \\. \\* \\? \\[ \\]
+        - Test patterns on a small set before broad searches
+        - Use word boundaries (\\b) for exact word matching
+      DESC
+
+      param :pattern,
+        desc: "Regular expression pattern to search for",
+        required: true
+
+      param :path,
+        desc: "Limit search to specific path (e.g., 'concept/', 'fact/api-design/', 'skill/ruby/blocks.md')",
+        required: false
+
+      param :case_insensitive,
+        type: "boolean",
+        desc: "Set to true for case-insensitive search (default: false)",
+        required: false
+
+      param :output_mode,
+        desc: "Output mode: 'files_with_matches' (default), 'content', or 'count'",
+        required: false
+
+      # Initialize with storage instance
+      #
+      # @param storage [Core::Storage] Storage instance
+      def initialize(storage:)
+        super()
+        @storage = storage
+      end
+
+      # Override name to return simple "MemoryGrep"
+      def name
+        "MemoryGrep"
+      end
+
+      # Execute the tool
+      #
+      # @param pattern [String] Regex pattern to search for
+      # @param path [String, nil] Optional path filter
+      # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+      # @param output_mode [String] Output mode
+      # @return [String] Formatted search results
+      def execute(pattern:, path: nil, case_insensitive: false, output_mode: "files_with_matches")
+        results = @storage.grep(
+          pattern: pattern,
+          path: path,
+          case_insensitive: case_insensitive,
+          output_mode: output_mode,
+        )
+
+        format_results(results, pattern, output_mode, path)
+      rescue ArgumentError => e
+        validation_error(e.message)
+      rescue RegexpError => e
+        validation_error("Invalid regex pattern: #{e.message}")
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def format_results(results, pattern, output_mode, path_filter)
+        case output_mode
+        when "files_with_matches"
+          format_files_with_matches(results, pattern, path_filter)
+        when "content"
+          format_content(results, pattern, path_filter)
+        when "count"
+          format_count(results, pattern, path_filter)
+        else
+          validation_error("Invalid output_mode: #{output_mode}")
+        end
+      end
+
+      def format_search_header(pattern, path_filter)
+        if path_filter && !path_filter.empty?
+          "'#{pattern}' in #{path_filter}"
+        else
+          "'#{pattern}'"
+        end
+      end
+
+      def format_files_with_matches(paths, pattern, path_filter)
+        search_desc = format_search_header(pattern, path_filter)
+
+        if paths.empty?
+          return "No matches found for pattern #{search_desc}"
+        end
+
+        result = []
+        result << "Memory entries matching #{search_desc} (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
+        paths.each do |path|
+          result << "  memory://#{path}"
+        end
+        result.join("\n")
+      end
+
+      def format_content(results, pattern, path_filter)
+        search_desc = format_search_header(pattern, path_filter)
+
+        if results.empty?
+          return "No matches found for pattern #{search_desc}"
+        end
+
+        total_matches = results.sum { |r| r[:matches].size }
+        output = []
+        output << "Memory entries matching #{search_desc} (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
+        output << ""
+
+        results.each do |result|
+          output << "memory://#{result[:path]}:"
+          result[:matches].each do |match|
+            output << "  #{match[:line_number]}: #{match[:content]}"
+          end
+          output << ""
+        end
+
+        output.join("\n").rstrip
+      end
+
+      def format_count(results, pattern, path_filter)
+        search_desc = format_search_header(pattern, path_filter)
+
+        if results.empty?
+          return "No matches found for pattern #{search_desc}"
+        end
+
+        total_matches = results.sum { |r| r[:count] }
+        output = []
+        output << "Memory entries matching #{search_desc} (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
+
+        results.each do |result|
+          output << "  memory://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/swarm_memory/tools/memory_multi_edit.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Tool for performing multiple edits to a memory entry
+    #
+    # Applies multiple edit operations sequentially to a single memory entry.
+    # Each edit sees the result of all previous edits, allowing for
+    # coordinated multi-step transformations.
+    # Each agent has its own isolated memory storage.
+    class MemoryMultiEdit < RubyLLM::Tool
+      description <<~DESC
+        Perform multiple exact string replacements in a single memory entry (applies edits sequentially).
+
+        REQUIRED: Provide BOTH parameters - file_path and edits_json.
+
+        **Required Parameters:**
+        - file_path (REQUIRED): Path to memory entry - MUST start with concept/, fact/, skill/, or experience/
+        - edits_json (REQUIRED): JSON array of edit operations - each must have old_string, new_string, and optionally replace_all
+
+        **MEMORY STRUCTURE (4 Fixed Categories Only):**
+        - concept/{domain}/** - Abstract ideas
+        - fact/{subfolder}/** - Concrete information
+        - skill/{domain}/** - Procedures
+        - experience/** - Lessons
+        INVALID: documentation/, reference/, project/, code/, parallel/
+
+        **JSON Format:**
+        ```json
+        [
+          {"old_string": "text to find", "new_string": "replacement text", "replace_all": false},
+          {"old_string": "another find", "new_string": "another replace", "replace_all": true}
+        ]
+        ```
+
+        **CRITICAL - Before Using This Tool:**
+        1. You MUST use MemoryRead on the entry first - edits without reading will FAIL
+        2. Copy text exactly from MemoryRead output, EXCLUDING the line number prefix
+        3. Line number format: "    123→actual content" - only use text AFTER the arrow
+        4. Edits are applied SEQUENTIALLY - later edits see results of earlier edits
+        5. If ANY edit fails, NO changes are saved (all-or-nothing)
+
+        **How Sequential Edits Work:**
+        ```
+        Original: "status: pending, priority: low"
+
+        Edit 1: "pending" → "in-progress"
+        Result: "status: in-progress, priority: low"
+
+        Edit 2: "low" → "high"  (sees Edit 1's result)
+        Final: "status: in-progress, priority: high"
+        ```
+
+        **Use Cases:**
+        - Making multiple coordinated changes in one operation
+        - Updating several related fields at once
+        - Chaining transformations where order matters
+        - Bulk find-and-replace operations
+
+        **Examples:**
+        ```
+        # Update multiple fields in an experience
+        MemoryMultiEdit(
+          file_path: "experience/api-debugging.md",
+          edits_json: '[
+            {"old_string": "status: in-progress", "new_string": "status: resolved"},
+            {"old_string": "confidence: medium", "new_string": "confidence: high"}
+          ]'
+        )
+
+        # Rename function and update calls in a concept
+        MemoryMultiEdit(
+          file_path: "concept/ruby/functions.md",
+          edits_json: '[
+            {"old_string": "def old_func_name", "new_string": "def new_func_name"},
+            {"old_string": "old_func_name()", "new_string": "new_func_name()", "replace_all": true}
+          ]'
+        )
+        ```
+
+        **Important Notes:**
+        - All edits in the array must be valid JSON objects
+        - Each old_string must be different from its new_string
+        - Each old_string must be unique in content UNLESS replace_all is true
+        - Failed edit shows which previous edits succeeded
+        - More efficient than multiple MemoryEdit calls
+      DESC
+
+      param :file_path,
+        desc: "Path to memory entry - MUST start with concept/, fact/, skill/, or experience/ (e.g., 'experience/api-debugging.md', 'concept/ruby/functions.md')",
+        required: true
+
+      param :edits_json,
+        type: "string",
+        desc: <<~DESC.chomp,
+          JSON array of edit operations. Each edit must have:
+          old_string (exact text to replace),
+          new_string (replacement text),
+          and optionally replace_all (boolean, default false).
+          Example: [{"old_string":"foo","new_string":"bar","replace_all":false}]
+        DESC
+        required: true
+
+      # Initialize with storage instance and agent name
+      #
+      # @param storage [Core::Storage] Storage instance
+      # @param agent_name [String, Symbol] Agent identifier
+      def initialize(storage:, agent_name:)
+        super()
+        @storage = storage
+        @agent_name = agent_name.to_sym
+      end
+
+      # Override name to return simple "MemoryMultiEdit"
+      def name
+        "MemoryMultiEdit"
+      end
+
+      # Execute the tool
+      #
+      # @param file_path [String] Path to memory entry
+      # @param edits_json [String] JSON array of edit operations
+      # @return [String] Success message or error
+      def execute(file_path:, edits_json:)
+        # Validate inputs
+        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+
+        # Parse JSON
+        edits = begin
+          JSON.parse(edits_json)
+        rescue JSON::ParserError
+          nil
+        end
+
+        return validation_error("Invalid JSON format. Please provide a valid JSON array of edit operations.") if edits.nil?
+
+        return validation_error("edits must be an array") unless edits.is_a?(Array)
+        return validation_error("edits array cannot be empty") if edits.empty?
+
+        # Read current content (this will raise ArgumentError if entry doesn't exist)
+        content = @storage.read(file_path: file_path)
+
+        # Enforce read-before-edit
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+          return validation_error(
+            "Cannot edit memory entry without reading it first. " \
+              "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \
+              "This ensures you have the current content to match against.",
+          )
+        end
+
+        # Validate edit operations
+        validated_edits = []
+        edits.each_with_index do |edit, index|
+          unless edit.is_a?(Hash)
+            return validation_error("Edit at index #{index} must be a hash/object with old_string and new_string")
+          end
+
+          # Convert string keys to symbols for consistency
+          edit = edit.transform_keys(&:to_sym)
+
+          unless edit[:old_string]
+            return validation_error("Edit at index #{index} missing required field 'old_string'")
+          end
+
+          unless edit[:new_string]
+            return validation_error("Edit at index #{index} missing required field 'new_string'")
+          end
+
+          # old_string and new_string must be different
+          if edit[:old_string] == edit[:new_string]
+            return validation_error("Edit at index #{index}: old_string and new_string must be different")
+          end
+
+          validated_edits << {
+            old_string: edit[:old_string].to_s,
+            new_string: edit[:new_string].to_s,
+            replace_all: edit[:replace_all] == true,
+            index: index,
+          }
+        end
+
+        # Apply edits sequentially
+        results = []
+        current_content = content
+
+        validated_edits.each do |edit|
+          # Check if old_string exists in current content
+          unless current_content.include?(edit[:old_string])
+            return error_with_results(
+              <<~ERROR.chomp,
+                Edit #{edit[:index]}: old_string not found in memory entry.
+                Make sure it matches exactly, including all whitespace and indentation.
+                Do not include line number prefixes from MemoryRead tool output.
+                Note: This edit follows #{edit[:index]} previous edit(s) which may have changed the content.
+              ERROR
+              results,
+            )
+          end
+
+          # Count occurrences
+          occurrences = current_content.scan(edit[:old_string]).count
+
+          # If not replace_all and multiple occurrences, error
+          if !edit[:replace_all] && occurrences > 1
+            return error_with_results(
+              <<~ERROR.chomp,
+                Edit #{edit[:index]}: Found #{occurrences} occurrences of old_string.
+                Either provide more surrounding context to make the match unique, or set replace_all: true to replace all occurrences.
+              ERROR
+              results,
+            )
+          end
+
+          # Perform replacement
+          new_content = if edit[:replace_all]
+            current_content.gsub(edit[:old_string], edit[:new_string])
+          else
+            current_content.sub(edit[:old_string], edit[:new_string])
+          end
+
+          # Record result
+          replaced_count = edit[:replace_all] ? occurrences : 1
+          results << {
+            index: edit[:index],
+            status: "success",
+            occurrences: replaced_count,
+            message: "Replaced #{replaced_count} occurrence(s)",
+          }
+
+          # Update content for next edit
+          current_content = new_content
+        end
+
+        # Get existing entry
+        entry = @storage.read_entry(file_path: file_path)
+
+        # Write updated content back (preserving the title)
+        @storage.write(
+          file_path: file_path,
+          content: current_content,
+          title: entry.title,
+        )
+
+        # Build success message
+        total_replacements = results.sum { |r| r[:occurrences] }
+        message = "Successfully applied #{validated_edits.size} edit(s) to memory://#{file_path}\n"
+        message += "Total replacements: #{total_replacements}\n\n"
+        message += "Details:\n"
+        results.each do |result|
+          message += "  Edit #{result[:index]}: #{result[:message]}\n"
+        end
+
+        message
+      rescue ArgumentError => e
+        validation_error(e.message)
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error_with_results(message, results)
+        output = "<tool_use_error>InputValidationError: #{message}\n\n"
+
+        if results.any?
+          output += "Previous successful edits before error:\n"
+          results.each do |result|
+            output += "  Edit #{result[:index]}: #{result[:message]}\n"
+          end
+          output += "\n"
+        end
+
+        output += "Note: The memory entry has NOT been modified. All or nothing approach - if any edit fails, no changes are saved.</tool_use_error>"
+        output
+      end
+    end
+  end
+end