claude_swarm 1.0.1 → 1.0.4

data/lib/swarm_memory/search/semantic_search.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Search
+    # Semantic search using embedding similarity
+    #
+    # Finds entries similar to a query based on embedding vectors
+    # rather than exact text matching.
+    class SemanticSearch
+      # Initialize semantic search
+      #
+      # @param adapter [Adapters::Base] Storage adapter
+      # @param embedder [Embeddings::Embedder] Embedder for generating query vectors
+      def initialize(adapter:, embedder:)
+        @adapter = adapter
+        @embedder = embedder
+      end
+
+      # Search for entries similar to query
+      #
+      # @param query [String] Search query
+      # @param top_k [Integer] Number of results to return
+      # @param threshold [Float] Minimum similarity threshold (0.0-1.0)
+      # @return [Array<Hash>] Ranked results with similarity scores
+      #
+      # @example
+      #   results = search.find_similar(
+      #     query: "How do I test Ruby code?",
+      #     top_k: 5,
+      #     threshold: 0.7
+      #   )
+      #   # => [
+      #   #   { path: "skills/testing/minitest", similarity: 0.92, title: "..." },
+      #   #   { path: "concepts/ruby/testing", similarity: 0.85, title: "..." }
+      #   # ]
+      def find_similar(query:, top_k: 5, threshold: 0.7)
+        raise ArgumentError, "query is required" if query.nil? || query.to_s.strip.empty?
+
+        # Generate query embedding
+        query_embedding = @embedder.embed(query)
+
+        # Get all entries with embeddings
+        all_entries = @adapter.all_entries
+        entries_with_embeddings = all_entries.select { |_, entry| entry.embedded? }
+
+        return [] if entries_with_embeddings.empty?
+
+        # Calculate similarities
+        similarities = entries_with_embeddings.map do |path, entry|
+          similarity = TextSimilarity.cosine(query_embedding, entry.embedding)
+
+          {
+            path: path,
+            title: entry.title,
+            similarity: similarity,
+            updated_at: entry.updated_at,
+          }
+        end
+
+        # Filter by threshold and sort by similarity (descending)
+        results = similarities
+          .select { |r| r[:similarity] >= threshold }
+          .sort_by { |r| -r[:similarity] }
+          .take(top_k)
+
+        results
+      end
+
+      # Find entries similar to a given entry
+      #
+      # @param file_path [String] Path to reference entry
+      # @param top_k [Integer] Number of results to return
+      # @param threshold [Float] Minimum similarity threshold
+      # @return [Array<Hash>] Ranked results (excluding the reference entry)
+      def find_similar_to_entry(file_path:, top_k: 5, threshold: 0.7)
+        # Get reference entry
+        reference_entry = @adapter.read_entry(file_path: file_path)
+
+        unless reference_entry.embedded?
+          raise SearchError, "Entry #{file_path} has no embedding. Cannot perform semantic search."
+        end
+
+        # Get all entries with embeddings (excluding reference)
+        all_entries = @adapter.all_entries
+        entries_with_embeddings = all_entries
+          .select { |path, entry| path != file_path && entry.embedded? }
+
+        return [] if entries_with_embeddings.empty?
+
+        # Calculate similarities
+        similarities = entries_with_embeddings.map do |path, entry|
+          similarity = TextSimilarity.cosine(reference_entry.embedding, entry.embedding)
+
+          {
+            path: path,
+            title: entry.title,
+            similarity: similarity,
+            updated_at: entry.updated_at,
+          }
+        end
+
+        # Filter by threshold and sort by similarity (descending)
+        results = similarities
+          .select { |r| r[:similarity] >= threshold }
+          .sort_by { |r| -r[:similarity] }
+          .take(top_k)
+
+        results
+      end
+    end
+  end
+end

data/lib/swarm_memory/search/text_search.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Search
+    # Text-based search operations (glob and grep)
+    #
+    # Provides a clean API for text-based search that wraps adapter operations.
+    # This layer could add additional logic like query parsing, ranking, etc.
+    class TextSearch
+      # Initialize text search
+      #
+      # @param adapter [Adapters::Base] Storage adapter
+      def initialize(adapter:)
+        @adapter = adapter
+      end
+
+      # Search by glob pattern
+      #
+      # @param pattern [String] Glob pattern
+      # @return [Array<Hash>] Matching entries
+      def glob(pattern:)
+        @adapter.glob(pattern: pattern)
+      end
+
+      # Search by content pattern
+      #
+      # @param pattern [String] Regex pattern
+      # @param case_insensitive [Boolean] Case-insensitive search
+      # @param output_mode [String] Output mode
+      # @param path [String, nil] Optional path prefix filter
+      # @return [Array<Hash>] Search results
+      def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches", path: nil)
+        @adapter.grep(
+          pattern: pattern,
+          case_insensitive: case_insensitive,
+          output_mode: output_mode,
+          path: path,
+        )
+      end
+    end
+  end
+end

data/lib/swarm_memory/search/text_similarity.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Search
+    # Text similarity calculations using multiple algorithms
+    #
+    # Provides both Jaccard (word overlap) and cosine similarity metrics.
+    class TextSimilarity
+      class << self
+        # Calculate Jaccard similarity between two texts
+        #
+        # Jaccard similarity measures the overlap of word sets.
+        # Score ranges from 0.0 (no overlap) to 1.0 (identical).
+        #
+        # @param text1 [String] First text
+        # @param text2 [String] Second text
+        # @return [Float] Similarity score 0.0-1.0
+        #
+        # @example
+        #   TextSimilarity.jaccard("ruby classes", "ruby modules")
+        #   # => 0.33 (1 shared word out of 3 total unique words)
+        def jaccard(text1, text2)
+          words1 = tokenize(text1)
+          words2 = tokenize(text2)
+
+          return 0.0 if words1.empty? && words2.empty?
+          return 0.0 if words1.empty? || words2.empty?
+
+          intersection = (words1 & words2).size
+          union = (words1 | words2).size
+
+          return 0.0 if union.zero?
+
+          intersection.to_f / union
+        end
+
+        # Calculate cosine similarity between two embedding vectors
+        #
+        # Cosine similarity measures the angle between vectors.
+        # Score ranges from -1.0 to 1.0 (0.0-1.0 for normalized embeddings).
+        #
+        # @param vec1 [Array<Float>] First embedding vector
+        # @param vec2 [Array<Float>] Second embedding vector
+        # @return [Float] Similarity score -1.0 to 1.0
+        #
+        # @example
+        #   vec1 = [0.1, 0.2, 0.3]
+        #   vec2 = [0.2, 0.3, 0.4]
+        #   TextSimilarity.cosine(vec1, vec2)
+        #   # => 0.99 (very similar)
+        def cosine(vec1, vec2)
+          raise ArgumentError, "Vectors must have same length" if vec1.size != vec2.size
+          return 0.0 if vec1.empty?
+
+          dot_product = vec1.zip(vec2).sum { |a, b| a * b }
+          magnitude1 = Math.sqrt(vec1.sum { |x| x * x })
+          magnitude2 = Math.sqrt(vec2.sum { |x| x * x })
+
+          return 0.0 if magnitude1.zero? || magnitude2.zero?
+
+          dot_product / (magnitude1 * magnitude2)
+        end
+
+        private
+
+        # Tokenize text into normalized words
+        #
+        # @param text [String] Text to tokenize
+        # @return [Set<String>] Set of normalized words
+        def tokenize(text)
+          text
+            .downcase
+            .scan(/\w+/) # Extract words only
+            .reject { |w| w.length < 3 } # Remove very short words (a, is, to, etc.)
+            .to_set
+        end
+      end
+    end
+  end
+end

data/lib/swarm_memory/skills/meta/deep-learning.md

@@ -0,0 +1,101 @@
+# Deep Learning Protocol
+
+Use this when asked to learn deeply about a topic.
+
+## CRITICAL: Use Memory Tools ONLY
+
+**NEVER use Write, Edit, or file tools during learning.**
+
+All knowledge MUST be stored using Memory* tools:
+- MemoryWrite - Store concepts, facts, skills
+- MemoryRead - Recall what you've learned
+- MemoryGrep - Search your knowledge
+- MemoryEdit - Update existing knowledge
+
+**Do NOT:**
+- Write to disk files (Write, Edit, MultiEdit)
+- Create temporary files
+- Store knowledge anywhere except Memory
+
+**Only use Memory* tools for persistence.**
+
+## Steps
+
+1. **Define Scope**
+   - What does "knowing this" mean?
+   - What should I be able to do with this knowledge?
+   - What are the boundaries of this topic?
+
+2. **Research Broadly** (Overview)
+   - Official documentation (WebFetch)
+   - Key concepts and terminology
+   - Main use cases and applications
+   - **Use MemoryWrite** to store concept entries for high-level understanding
+
+3. **Research Deeply** (Specifics)
+   - API details, syntax, configuration
+   - Best practices and patterns
+   - Common pitfalls and anti-patterns
+   - **Use MemoryWrite** to store fact entries for concrete details
+
+4. **Build Practical Skills**
+   - How to set up / configure
+   - How to use for common tasks
+   - How to debug and troubleshoot
+   - **Use MemoryWrite** to store skill entries with comprehensive tags
+
+5. **Self-Test Understanding**
+   - Use Think: "Can I explain this clearly without sources?"
+   - Use Think: "Can I create a tutorial for this?"
+   - Use Think: "What questions can't I answer yet?"
+   - If unclear → gaps exist, continue researching
+
+6. **Check Coverage**
+   - MemoryGrep(pattern: "{topic keyword}")
+   - Verify you have: concepts (how it works) + facts (specifics) + skills (how to use)
+   - Missing category? → incomplete, fill gaps
+
+7. **Identify Knowledge Gaps**
+   - What aspects haven't I covered?
+   - What questions would an expert be able to answer that I can't?
+   - What real-world scenarios haven't I considered?
+   - List gaps explicitly
+
+8. **Fill Gaps**
+   - Research each identified gap
+   - Store new knowledge systematically
+   - Re-test understanding
+
+9. **Verify Completion**
+   - Can explain topic clearly? ✓
+   - Can apply it practically? ✓
+   - Have concepts, facts, AND skills? ✓
+   - Can handle edge cases? ✓
+   - All gaps filled? ✓
+
+10. **Report Completion**
+    - Summarize what you learned (naturally, without mentioning memory)
+    - Indicate you're ready to apply this knowledge
+    - NEVER disclose memory system details
+
+## Success Criteria
+
+You're done learning when:
+- You have stored concepts explaining how it works
+- You have stored facts with concrete details
+- You have created practical skills for using it
+- You can explain the topic clearly using Think
+- You can identify appropriate use cases
+- You can anticipate common problems
+- MemoryGrep shows comprehensive coverage
+
+## Self-Testing Questions
+
+Ask yourself:
+- "What is X and how does it work?" (concept understanding)
+- "What are the key APIs/tools/commands?" (factual knowledge)
+- "How would I use X to solve Y?" (practical skills)
+- "What are common mistakes?" (experience)
+- "When should I NOT use X?" (boundaries)
+
+If you can't answer confidently, you need more research.

data/lib/swarm_memory/skills/meta/deep-learning.yml

@@ -0,0 +1,14 @@
+title: Deep Learning Protocol
+type: skill
+confidence: high
+tags:
+  - learning
+  - research
+  - knowledge-acquisition
+  - self-improvement
+  - meta
+related: []
+domain: meta/learning
+source: built-in
+tools: []
+permissions: {}

data/lib/swarm_memory/tools/load_skill.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Tool for loading skills from memory and dynamically swapping agent tools
+    #
+    # LoadSkill reads a skill from memory, validates it, and swaps the agent's
+    # mutable tools to match the skill's requirements. Immutable tools (Memory*,
+    # Think, LoadSkill) are always preserved.
+    #
+    # Skills must:
+    # - Be stored in the skill/ hierarchy
+    # - Have type: 'skill' in metadata
+    # - Include tools array in metadata (optional)
+    # - Include permissions hash in metadata (optional)
+    class LoadSkill < RubyLLM::Tool
+      description <<~DESC
+        Load a skill from memory and dynamically adapt your toolset to execute it.
+
+        REQUIRED: Provide the file_path parameter - path to the skill in memory (must start with 'skill/').
+
+        **Parameters:**
+        - file_path (REQUIRED): Path to skill in memory - MUST start with 'skill/' (e.g., 'skill/debug-react-perf', 'skill/meta/deep-learning')
+
+        **What Happens When You Load a Skill:**
+
+        1. **Tool Swapping**: Your mutable tools are replaced with the skill's required tools
+           - Immutable tools (Memory*, LoadSkill) always remain available
+           - Skill's tool list completely replaces your current mutable tools
+
+        2. **Permissions Applied**: Tool permissions from skill metadata are applied
+           - Skill permissions override agent default permissions
+           - Allows/denies specific tool actions as defined in skill
+
+        3. **Skill Content Returned**: Returns the skill's step-by-step instructions
+           - Read and follow the instructions carefully
+           - Instructions are formatted with line numbers
+
+        4. **System Reminder Injected**: You'll see your complete updated toolset
+           - Lists all tools now available to you
+           - Only use tools from the updated list
+
+        **Skill Requirements:**
+
+        Skills MUST:
+        - Be stored in skill/ hierarchy ONLY (skill/ is one of exactly 4 memory categories)
+        - Path MUST start with 'skill/' (e.g., 'skill/debugging/api.md', 'skill/meta/deep-learning.md')
+        - Have type: 'skill' in metadata
+        - Optionally specify tools array in metadata
+        - Optionally specify permissions hash in metadata
+
+        **MEMORY CATEGORIES (4 Fixed Only):**
+        concept/, fact/, skill/, experience/ - NO OTHER top-level categories exist
+
+        **Skill Metadata Example:**
+        ```yaml
+        type: skill
+        tools: [Read, Edit, Bash, Grep]
+        permissions:
+          Bash:
+            allow_commands: ["npm", "pytest", "bundle"]
+            deny_commands: ["rm", "sudo"]
+        tags: [debugging, react, performance]
+        ```
+
+        **Usage Flow:**
+
+        ```
+        # 1. Find available skills (skill/ is one of 4 fixed memory categories)
+        MemoryGlob(pattern: "skill/**")
+
+        # 2. Read skill to understand it
+        MemoryRead(file_path: "skill/debugging/api-errors.md")
+
+        # 3. Load skill to adapt tools and get instructions
+        LoadSkill(file_path: "skill/debugging/api-errors.md")
+
+        # 4. Follow the skill's instructions using your updated toolset
+        ```
+
+        **Examples:**
+
+        ```
+        # Load a debugging skill
+        LoadSkill(file_path: "skill/debugging/api-errors.md")
+
+        # Load a meta-skill (skills about skills)
+        LoadSkill(file_path: "skill/meta/deep-learning.md")
+
+        # Load a testing skill
+        LoadSkill(file_path: "skill/testing/unit-tests.md")
+        ```
+
+        **Important Notes:**
+
+        - **Read Before Loading**: Use MemoryRead first to see what the skill does
+        - **Tool Swap**: Loading a skill changes your available tools - be aware of this
+        - **Immutable Tools**: Memory tools and LoadSkill are NEVER removed
+        - **Follow Instructions**: The skill content provides step-by-step guidance
+        - **One Skill at a Time**: Loading a new skill replaces the previous skill's toolset
+        - **Skill Validation**: Tool will fail if path doesn't start with 'skill/' or entry isn't type: 'skill'
+
+        **Skill Types:**
+
+        1. **Task Skills**: Specific procedures (debugging, testing, refactoring)
+        2. **Meta-Skills**: Skills about skills (deep-learning, skill-creation)
+        3. **Domain Skills**: Specialized knowledge (frontend, backend, data-analysis)
+
+        **Creating Your Own Skills:**
+
+        Skills are just memory entries with special metadata. To create one:
+        1. Write step-by-step instructions in markdown
+        2. Store in skill/ hierarchy
+        3. Add metadata: type='skill', tools array, optional permissions
+        4. Test by loading and following instructions
+
+        **Common Use Cases:**
+
+        - Following established procedures consistently
+        - Accessing specialized toolsets for specific tasks
+        - Learning new workflows via step-by-step guidance
+        - Enforcing tool restrictions for safety
+        - Standardizing approaches across sessions
+      DESC
+
+      param :file_path,
+        desc: "Path to skill - MUST start with 'skill/' (one of 4 fixed memory categories). Examples: 'skill/debugging/api-errors.md', 'skill/meta/deep-learning.md'",
+        required: true
+
+      # Initialize with all context needed for tool swapping
+      #
+      # @param storage [Core::Storage] Memory storage
+      # @param agent_name [Symbol] Agent identifier
+      # @param chat [SwarmSDK::Agent::Chat] The agent's chat instance
+      # @param tool_configurator [SwarmSDK::ToolConfigurator] For creating tools
+      # @param agent_definition [SwarmSDK::Agent::Definition] For permissions
+      def initialize(storage:, agent_name:, chat:, tool_configurator:, agent_definition:)
+        super()
+        @storage = storage
+        @agent_name = agent_name
+        @chat = chat
+        @tool_configurator = tool_configurator
+        @agent_definition = agent_definition
+
+        # Mark memory tools and LoadSkill as immutable
+        # This ensures they won't be removed during skill swapping
+        @chat.mark_tools_immutable(
+          "MemoryWrite",
+          "MemoryRead",
+          "MemoryEdit",
+          "MemoryMultiEdit",
+          "MemoryDelete",
+          "MemoryGlob",
+          "MemoryGrep",
+          "MemoryDefrag",
+          "LoadSkill",
+        )
+      end
+
+      # Override name to return simple "LoadSkill"
+      def name
+        "LoadSkill"
+      end
+
+      # Execute the tool
+      #
+      # @param file_path [String] Path to skill in memory
+      # @return [String] Skill content with line numbers, or error message
+      def execute(file_path:)
+        # 1. Validate path starts with skill/
+        unless file_path.start_with?("skill/")
+          return validation_error("Skills must be stored in skill/ hierarchy. Got: #{file_path}")
+        end
+
+        # 2. Read entry with metadata
+        begin
+          entry = @storage.read_entry(file_path: file_path)
+        rescue ArgumentError => e
+          return validation_error(e.message)
+        end
+
+        # 3. Validate it's a skill
+        unless entry.metadata && entry.metadata["type"] == "skill"
+          type = entry.metadata&.dig("type") || "none"
+          return validation_error("memory://#{file_path} is not a skill (type: #{type})")
+        end
+
+        # 4. Extract tool requirements
+        required_tools = entry.metadata["tools"]
+        permissions = entry.metadata["permissions"] || {}
+
+        # 5. Validate and swap tools (only if tools are specified)
+        if required_tools && !required_tools.empty?
+          begin
+            swap_tools(required_tools, permissions)
+          rescue ArgumentError => e
+            return validation_error(e.message)
+          end
+        end
+        # If no tools specified (nil or []), keep current tools (no swap)
+
+        # 6. Mark skill as loaded
+        @chat.mark_skill_loaded(file_path)
+
+        # 7. Return content with confirmation message
+        title = entry.title || "Untitled Skill"
+        result = "Loaded skill: #{title}\n\n"
+        result += format_with_line_numbers(entry.content)
+
+        # 8. Add system reminder if tools were swapped
+        if required_tools && !required_tools.empty?
+          result += "\n\n"
+          result += build_toolset_update_reminder(required_tools)
+        end
+
+        result
+      end
+
+      private
+
+      # Build system reminder for toolset updates
+      #
+      # @param new_tools [Array<String>] Tools that were added
+      # @return [String] System reminder message
+      def build_toolset_update_reminder(new_tools)
+        # Get current tool list from chat
+        # Handle both real Chat (hash) and MockChat (array)
+        tools_collection = @chat.tools
+        current_tools = if tools_collection.is_a?(Hash)
+          tools_collection.values.map(&:name).sort
+        else
+          tools_collection.map(&:name).sort
+        end
+
+        reminder = "<system-reminder>\n"
+        reminder += "Your available tools have been updated.\n\n"
+        reminder += "New tools loaded from skill:\n"
+        new_tools.each do |tool_name|
+          reminder += "  - #{tool_name}\n"
+        end
+        reminder += "\nYour complete toolset is now:\n"
+        current_tools.each do |tool_name|
+          reminder += "  - #{tool_name}\n"
+        end
+        reminder += "\nOnly use tools from this list. Do not attempt to use tools that are not listed here.\n"
+        reminder += "</system-reminder>"
+
+        reminder
+      end
+
+      # Swap agent tools to match skill requirements
+      #
+      # @param required_tools [Array<String>] Tools needed by the skill
+      # @param permissions [Hash] Tool permissions from skill metadata
+      # @return [void]
+      # @raise [ArgumentError] If validation fails
+      def swap_tools(required_tools, permissions)
+        # Future: Could validate tool availability against agent's configured tools
+        # For now, all tools in SwarmSDK are available (unless bypassed by permissions)
+
+        # Remove all mutable tools (keeps immutable tools)
+        @chat.remove_mutable_tools
+
+        # Add required tools from skill
+        required_tools.each do |tool_name|
+          tool_sym = tool_name.to_sym
+
+          # Get permissions for this tool (skill overrides agent permissions)
+          tool_permissions = permissions[tool_name] || permissions[tool_sym.to_s]
+
+          # Create tool instance
+          tool_instance = @tool_configurator.create_tool_instance(
+            tool_sym,
+            @agent_name,
+            @agent_definition.directory,
+          )
+
+          # Wrap with permissions (unless bypassed)
+          tool_instance = @tool_configurator.wrap_tool_with_permissions(
+            tool_instance,
+            tool_permissions,
+            @agent_definition,
+          )
+
+          # Add to chat
+          @chat.add_tool(tool_instance)
+        end
+      end
+
+      # Format validation error message
+      #
+      # @param message [String] Error message
+      # @return [String] Formatted error
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      # Format content with line numbers (same format as Read tool)
+      #
+      # @param content [String] Content to format
+      # @return [String] Content with line numbers
+      def format_with_line_numbers(content)
+        lines = content.lines
+        output_lines = lines.each_with_index.map do |line, idx|
+          line_number = idx + 1
+          display_line = line.chomp
+          "#{line_number.to_s.rjust(6)}→#{display_line}"
+        end
+        output_lines.join("\n")
+      end
+    end
+  end
+end