swarm_memory 2.2.5 → 2.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adb03d1c769f7c76bff25ce6150989948b0b217d809b4dc40f9cd3561cdd1c02
-  data.tar.gz: 14c0276ee61c49b2d0e6d70938846516067a716b55effb8b0927e178c24f35c8
+  metadata.gz: aa8c626431db042fc20905dc9aff6871b38ade85e1bbed5dd9a6770b2567ebbd
+  data.tar.gz: 947ebabdc79659228284e8d9af16b17763bcfc5ae471093fcc9f5678083abc91
 SHA512:
-  metadata.gz: 37d88e126bd894b358044d40b6d06ba039766483b3a1a5d0722b3aca883ddbb00ed43c92a2b86bf8f479dda8888b946271f011b62b2f6ef87e5aa6a34585e325
-  data.tar.gz: eb4fc576318665ec0ca0e497cb2dc687204f92f36deeff9407158ff43c6683ca70d1dca8798c10d7e14ad7b41835a6ab6127aee94805699cac2b8a758ee9b26e
+  metadata.gz: 7ff95190f7efb9328d1e5e20c5693cdf485806e74c56b9ace9bd01a1ad7bf486bda6c209b14a0034c35bab910d8be4c63c8c7dafe612a5b624674ad169cd19fd
+  data.tar.gz: 472e6ada1c0952e5feaf243bdd66339da09ff8bd4e043e4321bffbc6fd88e1973bef544e66a96eb74c50984e687b40c43b03a69bcee6032d49cb62d655a63be7

data/lib/swarm_memory/adapters/base.rb

@@ -101,6 +101,34 @@ module SwarmMemory
         raise NotImplementedError, "Subclass must implement #size"
       end
 
+      # Semantic search by embedding vector
+      #
+      # Searches all entries with embeddings and returns those similar to the query.
+      # Results are sorted by cosine similarity in descending order.
+      #
+      # @param embedding [Array<Float>] Query embedding vector
+      # @param top_k [Integer] Number of results to return
+      # @param threshold [Float] Minimum similarity score (0.0-1.0)
+      # @return [Array<Hash>] Results with similarity scores
+      #
+      # @example
+      #   results = adapter.semantic_search(
+      #     embedding: query_embedding,
+      #     top_k: 5,
+      #     threshold: 0.65
+      #   )
+      #
+      # Each result hash must contain:
+      #   - :path (String) - logical file path
+      #   - :similarity (Float) - cosine similarity score 0.0-1.0
+      #   - :title (String) - entry title
+      #   - :size (Integer) - content size in bytes
+      #   - :updated_at (Time) - last update timestamp
+      #   - :metadata (Hash) - nested hash with type, tags, domain, etc.
+      def semantic_search(embedding:, top_k: 10, threshold: 0.0)
+        raise NotImplementedError, "Subclass must implement #semantic_search"
+      end
+
       protected
 
       # Format bytes to human-readable size

data/lib/swarm_memory/dsl/builder_extension.rb

@@ -9,21 +9,21 @@ module SwarmMemory
     module BuilderExtension
       # Configure persistent memory for this agent
       #
-      # @example Interactive mode (default) - Learn and retrieve
+      # @example Read-write mode (default) - Learn and retrieve
       #   memory do
       #     directory ".swarm/agent-memory"
       #   end
       #
-      # @example Retrieval mode - Read-only Q&A
+      # @example Read-only mode - Q&A without learning
       #   memory do
       #     directory "team-knowledge/"
-      #     mode :retrieval
+      #     mode :read_only
       #   end
       #
-      # @example Researcher mode - Knowledge extraction
+      # @example Full access mode - Knowledge management with Delete and Defrag
       #   memory do
       #     directory "team-knowledge/"
-      #     mode :researcher
+      #     mode :full_access
       #   end
       def memory(&block)
         @memory_config = SwarmMemory::DSL::MemoryConfig.new

data/lib/swarm_memory/dsl/memory_config.rb

@@ -28,7 +28,7 @@ module SwarmMemory
       def initialize
         @adapter_type = :filesystem # Default adapter
         @adapter_options = {} # Options passed to adapter constructor
-        @mode = :assistant # Default mode
+        @mode = :read_write # Default mode
       end
 
       # DSL method to set/get adapter type
@@ -72,9 +72,9 @@ module SwarmMemory
       # DSL method to set/get mode
       #
       # Modes:
-      # - :assistant (default) - Read + Write, balanced for learning and retrieval
-      # - :retrieval - Read-only, optimized for Q&A
-      # - :researcher - All tools, optimized for knowledge extraction
+      # - :read_write (default) - Read + Write + Edit, balanced for learning and retrieval
+      # - :read_only - Read-only, optimized for Q&A
+      # - :full_access - All tools including Delete and Defrag, optimized for knowledge management
       #
       # @param value [Symbol, nil] Memory mode
       # @return [Symbol] Current mode

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -20,7 +20,7 @@ module SwarmMemory
         # Needed for semantic skill discovery in on_user_message
         @storages = {}
         # Track memory mode for each agent: { agent_name => mode }
-        # Modes: :assistant (default), :retrieval, :researcher
+        # Modes: :read_write (default), :read_only, :full_access
         @modes = {}
         # Track threshold configuration for each agent: { agent_name => config }
         # Enables per-adapter threshold tuning with ENV fallback
@@ -50,6 +50,7 @@ module SwarmMemory
           :MemoryRead,
           :MemoryGlob,
           :MemoryGrep,
+          :MemorySearch,
           :MemoryWrite,
           :MemoryEdit,
           :MemoryDelete,
@@ -63,26 +64,27 @@ module SwarmMemory
       # @return [Array<Symbol>] Tool names for this mode
       def tools_for_mode(mode)
         case mode
-        when :retrieval
+        when :read_only
           # Read-only tools for Q&A agents
-          [:MemoryRead, :MemoryGlob, :MemoryGrep]
-        when :assistant
-          # Read + Write + Edit for learning assistants (need edit for corrections)
-          [:MemoryRead, :MemoryGlob, :MemoryGrep, :MemoryWrite, :MemoryEdit]
-        when :researcher
-          # All tools for knowledge extraction
+          [:MemoryRead, :MemoryGlob, :MemoryGrep, :MemorySearch]
+        when :read_write
+          # Read + Write + Edit for learning agents (need edit for corrections)
+          [:MemoryRead, :MemoryGlob, :MemoryGrep, :MemorySearch, :MemoryWrite, :MemoryEdit]
+        when :full_access
+          # All tools for knowledge extraction and management
           [
             :MemoryRead,
             :MemoryGlob,
             :MemoryGrep,
+            :MemorySearch,
             :MemoryWrite,
             :MemoryEdit,
             :MemoryDelete,
             :MemoryDefrag,
           ]
         else
-          # Default to assistant
-          [:MemoryRead, :MemoryGlob, :MemoryGrep, :MemoryWrite, :MemoryEdit]
+          # Default to read_write
+          [:MemoryRead, :MemoryGlob, :MemoryGrep, :MemorySearch, :MemoryWrite, :MemoryEdit]
         end
       end
 
@@ -180,16 +182,16 @@ module SwarmMemory
         elsif memory_config.respond_to?(:mode)
           memory_config.mode # Other object with mode method
         elsif memory_config.is_a?(Hash)
-          (memory_config[:mode] || memory_config["mode"] || :assistant).to_sym
+          (memory_config[:mode] || memory_config["mode"] || :read_write).to_sym
         else
-          :assistant # Default mode
+          :read_write # Default mode
         end
 
         # Select prompt template based on mode
         prompt_filename = case mode
-        when :retrieval then "memory_retrieval.md.erb"
-        when :researcher then "memory_researcher.md.erb"
-        else "memory_assistant.md.erb" # Default
+        when :read_only then "memory_read_only.md.erb"
+        when :full_access then "memory_full_access.md.erb"
+        else "memory_read_write.md.erb" # Default
         end
 
         memory_prompt_path = File.expand_path("../prompts/#{prompt_filename}", __dir__)
@@ -209,8 +211,8 @@ module SwarmMemory
       def immutable_tools_for_mode(mode)
         base_tools = tools_for_mode(mode)
 
-        # LoadSkill only for assistant and researcher modes (not retrieval)
-        if mode == :retrieval
+        # LoadSkill only for read_write and full_access modes (not read_only)
+        if mode == :read_only
           base_tools
         else
           base_tools + [:LoadSkill]
@@ -390,8 +392,8 @@ module SwarmMemory
           agent.remove_tool(tool_name)
         end
 
-        # Create and register LoadSkill tool (NOT for retrieval mode - read-only)
-        unless mode == :retrieval
+        # Create and register LoadSkill tool (NOT for read_only mode)
+        unless mode == :read_only
           load_skill_tool = SwarmMemory.create_tool(
             :LoadSkill,
             storage: storage,

data/lib/swarm_memory/prompts/{memory_researcher.md.erb → memory_full_access.md.erb}

@@ -24,6 +24,7 @@ You have persistent memory that learns from conversations and helps you answer q
 
 **CRITICAL - These are your ONLY memory tools:**
 - `MemoryRead` - Read a specific memory
+- `MemorySearch` - Search memory by semantic similarity
 - `MemoryGrep` - Search memory by keyword pattern
 - `MemoryGlob` - Browse memory by path pattern
 - `MemoryWrite` - Create new memory
@@ -33,7 +34,6 @@ You have persistent memory that learns from conversations and helps you answer q
 - `LoadSkill` - Load a skill and swap tools
 
 **DO NOT use:**
-- ❌ "MemorySearch" (doesn't exist - use MemoryGrep)
 - ❌ Any other memory tool names
 
 ## CRITICAL: Every Memory MUST Have a Type

data/lib/swarm_memory/prompts/{memory_assistant.md.erb → memory_read_write.md.erb}

@@ -24,6 +24,7 @@ You have persistent memory that learns from conversations and helps you answer q
 
 **CRITICAL - These are your ONLY memory tools:**
 - `MemoryRead` - Read a specific memory
+- `MemorySearch` - Search memory by semantic similarity
 - `MemoryGrep` - Search memory by keyword pattern
 - `MemoryGlob` - Browse memory by path pattern
 - `MemoryWrite` - Create new memory
@@ -31,7 +32,6 @@ You have persistent memory that learns from conversations and helps you answer q
 - `LoadSkill` - Load a skill and swap tools
 
 **DO NOT use:**
-- ❌ "MemorySearch" (doesn't exist - use MemoryGrep)
 - ❌ Any other memory tool names
 
 ## CRITICAL: Every Memory MUST Have a Type

data/lib/swarm_memory/tools/memory_glob.rb

@@ -43,14 +43,6 @@ module SwarmMemory
         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, ...
@@ -66,10 +58,6 @@ module SwarmMemory
         # 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 **:**
@@ -92,15 +80,16 @@ module SwarmMemory
         **Tips:**
         - Start with broad patterns and narrow down
         - Use `**` for recursive searching entire hierarchies
+        - NEVER use `**` to search all categories at once, or all memories for a category. Always use specific patterns.
         - 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')",
+        desc: "Glob pattern - target concept/, fact/, skill/, or experience/ only (e.g., 'skill/debugging/*ruby*', 'concept/programming-languages/ruby*', 'fact/people/*john*')",
         required: true
 
-      MAX_RESULTS = 500 # Limit results to prevent overwhelming output
+      MAX_RESULTS = 50 # Limit results to prevent overwhelming output
 
       # Initialize with storage instance
       #

data/lib/swarm_memory/tools/memory_grep.rb

@@ -127,6 +127,8 @@ module SwarmMemory
         desc: "Output mode: 'files_with_matches' (default), 'content', or 'count'",
         required: false
 
+      MAX_RESULTS = 50 # Limit results to prevent overwhelming output
+
       # Initialize with storage instance
       #
       # @param storage [Core::Storage] Storage instance
@@ -196,12 +198,39 @@ module SwarmMemory
           return "No matches found for pattern #{search_desc}"
         end
 
+        # Limit results and track if truncated
+        original_count = paths.size
+        truncated = original_count > MAX_RESULTS
+        paths = paths.take(MAX_RESULTS) if truncated
+
         result = []
-        result << "Memory entries matching #{search_desc} (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
+        result << if truncated
+          "Memory entries matching #{search_desc} (showing #{paths.size} of #{original_count} entries):"
+        else
+          "Memory entries matching #{search_desc} (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
+        end
+
         paths.each do |path|
           result << "- #{format_memory_path_with_title(path)}"
         end
-        result.join("\n")
+
+        output = result.join("\n")
+
+        # Add system reminder if truncated
+        if truncated
+          output += <<~REMINDER
+
+            <system-reminder>
+            Results limited to first #{MAX_RESULTS} matches (sorted by most recently modified).
+            Your search returned #{original_count} total matches. Consider:
+            - Adding a path filter to narrow scope (e.g., path: "fact/api-design/")
+            - Using a more specific regex pattern
+            - Searching within a specific memory category (concept/, fact/, skill/, experience/)
+            </system-reminder>
+          REMINDER
+        end
+
+        output
       end
 
       def format_content(results, pattern, path_filter)
@@ -211,9 +240,21 @@ module SwarmMemory
           return "No matches found for pattern #{search_desc}"
         end
 
+        # Limit results and track if truncated
+        original_count = results.size
+        original_total_matches = results.sum { |r| r[:matches].size }
+        truncated = original_count > MAX_RESULTS
+        results = results.take(MAX_RESULTS) if truncated
+
         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 << if truncated
+          "Memory entries matching #{search_desc} (showing #{results.size} of #{original_count} entries, #{total_matches} of #{original_total_matches} matches):"
+        else
+          "Memory entries matching #{search_desc} (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
+        end
+
         output << ""
 
         results.each do |result|
@@ -224,7 +265,23 @@ module SwarmMemory
           output << ""
         end
 
-        output.join("\n").rstrip
+        result_text = output.join("\n").rstrip
+
+        # Add system reminder if truncated
+        if truncated
+          result_text += <<~REMINDER
+
+            <system-reminder>
+            Results limited to first #{MAX_RESULTS} entries.
+            Your search returned #{original_count} total entries with #{original_total_matches} matches. Consider:
+            - Adding a path filter to narrow scope (e.g., path: "fact/api-design/")
+            - Using a more specific regex pattern
+            - Searching within a specific memory category or subdomain
+            </system-reminder>
+          REMINDER
+        end
+
+        result_text
       end
 
       def format_count(results, pattern, path_filter)
@@ -234,15 +291,42 @@ module SwarmMemory
           return "No matches found for pattern #{search_desc}"
         end
 
+        # Limit results and track if truncated
+        original_count = results.size
+        original_total_matches = results.sum { |r| r[:count] }
+        truncated = original_count > MAX_RESULTS
+        results = results.take(MAX_RESULTS) if truncated
+
         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"}):"
+
+        output << if truncated
+          "Memory entries matching #{search_desc} (showing #{results.size} of #{original_count} entries, #{total_matches} of #{original_total_matches} total matches):"
+        else
+          "Memory entries matching #{search_desc} (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
+        end
 
         results.each do |result|
           output << "  memory://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
         end
 
-        output.join("\n")
+        result_text = output.join("\n")
+
+        # Add system reminder if truncated
+        if truncated
+          result_text += <<~REMINDER
+
+            <system-reminder>
+            Results limited to first #{MAX_RESULTS} entries.
+            Your search returned #{original_count} total entries with #{original_total_matches} matches. Consider:
+            - Adding a path filter to narrow scope (e.g., path: "fact/api-design/")
+            - Using a more specific regex pattern
+            - Searching within a specific memory category or subdomain
+            </system-reminder>
+          REMINDER
+        end
+
+        result_text
       end
     end
   end

data/lib/swarm_memory/tools/memory_search.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Tool for semantic search across memory entries
+    #
+    # Searches content stored in memory using AI embeddings to find
+    # conceptually related entries even when exact keywords don't match.
+    # Each agent has its own isolated memory storage.
+    class MemorySearch < RubyLLM::Tool
+      description <<~DESC
+        Perform semantic search across memory entries using natural language queries.
+
+        This tool uses AI embeddings to find conceptually related memories even when
+        exact keywords don't match. Results are ranked by semantic similarity and
+        filtered by specified criteria.
+
+        Use this tool when:
+        - Looking for concepts related to a topic (e.g., "authentication patterns")
+        - Exploring connections between ideas
+        - Finding memories when you don't know exact terminology
+        - Researching a subject area
+
+        Use MemoryGrep instead when:
+        - Searching for exact text or regex patterns
+        - Looking for specific code snippets or examples
+
+        Use MemoryGlob instead when:
+        - Browsing by path structure (e.g., "concept/ruby/*")
+        - Listing all memories in a category
+
+        Examples:
+          MemorySearch(query: "authentication patterns", top_k: 5, threshold: 0.5)
+          MemorySearch(query: "async programming", filter_type: "concept")
+          MemorySearch(query: "API design", filter_domain: "programming")
+      DESC
+
+      param :query,
+        type: "string",
+        desc: "Natural language search query describing what you're looking for",
+        required: true
+
+      param :top_k,
+        type: "integer",
+        desc: "Maximum number of results to return (default: 10, max: 100)",
+        required: false
+
+      param :threshold,
+        type: "number",
+        desc: "Minimum similarity score 0.0-1.0 (default: 0.0, higher = stricter)",
+        required: false
+
+      param :filter_type,
+        type: "string",
+        desc: "Filter by type: 'concept', 'fact', 'skill', 'experience', or comma-separated list",
+        required: false
+
+      param :filter_domain,
+        type: "string",
+        desc: "Filter by domain prefix (e.g., 'programming/ruby')",
+        required: false
+
+      # Maximum results to prevent context overflow
+      MAX_RESULTS = 50
+
+      # Initialize with storage instance
+      #
+      # @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 "MemorySearch"
+      def name
+        "MemorySearch"
+      end
+
+      # Execute the tool
+      #
+      # @param query [String] Natural language search query
+      # @param top_k [Integer] Maximum number of results
+      # @param threshold [Float] Minimum similarity score
+      # @param filter_type [String, nil] Type filter
+      # @param filter_domain [String, nil] Domain filter
+      # @return [String] Formatted search results
+      def execute(query:, top_k: 10, threshold: 0.0, filter_type: nil, filter_domain: nil)
+        # Reset state for multiple types post-filtering
+        @requested_types = nil
+
+        # 1. Check semantic index availability
+        unless @storage.semantic_index
+          return validation_error("Semantic search not available (no embedder configured)")
+        end
+
+        # 2. Validate parameters
+        top_k = validate_top_k(top_k)
+        return top_k if top_k.is_a?(String) # Error message
+
+        threshold = validate_threshold(threshold)
+        return threshold if threshold.is_a?(String) # Error message
+
+        # 3. Build filter hash (may set @requested_types for multi-type filtering)
+        filter = build_filter(filter_type, filter_domain)
+
+        # 4. Perform semantic search
+        # For multiple types, we get extra results to compensate for post-filtering
+        search_top_k = @requested_types && @requested_types.size > 1 ? top_k * 3 : top_k
+        results = @storage.semantic_index.search(
+          query: query,
+          top_k: search_top_k,
+          threshold: threshold,
+          filter: filter,
+        )
+
+        # 5. Format and return results (handles multi-type post-filtering)
+        format_results(results, query, threshold, top_k)
+      rescue StandardError => e
+        validation_error("Search failed: #{e.message}")
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def validate_top_k(value)
+        k = value.to_i
+        if k <= 0
+          return validation_error("top_k must be positive (got: #{value})")
+        end
+
+        [k, MAX_RESULTS].min
+      end
+
+      def validate_threshold(value)
+        t = value.to_f
+        if t < 0.0 || t > 1.0
+          return validation_error("threshold must be between 0.0 and 1.0 (got: #{value})")
+        end
+
+        t
+      end
+
+      def build_filter(filter_type, filter_domain)
+        filter = {}
+
+        # IMPORTANT: SemanticIndex's apply_filters uses equality checks (==)
+        # So filter["type"] = ["concept", "fact"] won't match metadata["type"] = "concept"
+        # For multiple types, we pass nil filter and post-filter results in Ruby
+        if filter_type
+          types = filter_type.split(",").map(&:strip)
+          if types.size == 1
+            # Single type: use SemanticIndex filter
+            filter["type"] = types.first
+          else
+            # Multiple types: will be filtered in format_results
+            # Store for post-filtering but don't add to SemanticIndex filter
+            @requested_types = types
+          end
+        end
+
+        # Domain can be used in filter (it's a string comparison)
+        filter["domain"] = filter_domain if filter_domain
+
+        filter.empty? ? nil : filter
+      end
+
+      def format_results(results, query, threshold, top_k)
+        # Post-filter for multiple types (if requested)
+        # This is needed because SemanticIndex's apply_filters only does equality checks
+        if @requested_types && @requested_types.size > 1
+          results = results.select do |result|
+            type = result.dig(:metadata, "type") || result.dig(:metadata, :type)
+            @requested_types.include?(type)
+          end
+        end
+
+        # Limit to requested top_k after filtering
+        results = results.take(top_k)
+
+        if results.empty?
+          return format_no_results(query, threshold)
+        end
+
+        header = "Found #{results.size} #{pluralize("memory", results.size)} " \
+          "matching \"#{query}\" (similarity >= #{threshold}):\n\n"
+
+        entries = results.map.with_index(1) do |result, idx|
+          format_result_entry(idx, result)
+        end
+
+        footer = "\n\nUse MemoryRead to view full content of any memory."
+
+        header + entries.join("\n\n") + footer
+      end
+
+      def format_no_results(query, threshold)
+        msg = "No memories found matching \"#{query}\""
+        msg += " with similarity >= #{threshold}" if threshold > 0.0
+        msg + ".\n\nTry:\n" \
+          "- Using a more general query\n" \
+          "- Lowering the threshold\n" \
+          "- Using MemoryGrep for keyword search\n" \
+          "- Using MemoryGlob to browse by path"
+      end
+
+      def format_result_entry(index, result)
+        lines = []
+        lines << "#{index}. memory://#{result[:path]} \"#{result[:title]}\" (score: #{format_score(result[:similarity])})"
+
+        # Add metadata for context (access nested metadata correctly)
+        metadata_parts = []
+        tags = result.dig(:metadata, "tags") || result.dig(:metadata, :tags)
+        domain = result.dig(:metadata, "domain") || result.dig(:metadata, :domain)
+        type = result.dig(:metadata, "type") || result.dig(:metadata, :type)
+
+        metadata_parts << "Tags: #{tags.join(", ")}" if tags&.any?
+        metadata_parts << "Domain: #{domain}" if domain
+        metadata_parts << "Type: #{type}" if type
+
+        lines << "   #{metadata_parts.join(" | ")}" if metadata_parts.any?
+
+        lines.join("\n")
+      end
+
+      def format_score(score)
+        format("%.2f", score)
+      end
+
+      def pluralize(word, count)
+        count == 1 ? word : "#{word.sub(/y$/, "ie")}s" # memory -> memories
+      end
+    end
+  end
+end

data/lib/swarm_memory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmMemory
-  VERSION = "2.2.5"
+  VERSION = "2.2.6"
 end

data/lib/swarm_memory.rb

@@ -121,6 +121,8 @@ module SwarmMemory
         Tools::MemoryWrite.new(storage: storage, agent_name: agent_name)
       when :MemoryRead
         Tools::MemoryRead.new(storage: storage, agent_name: agent_name)
+      when :MemorySearch
+        Tools::MemorySearch.new(storage: storage, agent_name: agent_name)
       when :MemoryEdit
         Tools::MemoryEdit.new(storage: storage, agent_name: agent_name)
       when :MemoryDelete

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_memory
 version: !ruby/object:Gem::Version
-  version: 2.2.5
+  version: 2.2.6
 platform: ruby
 authors:
 - Paulo Arruda
@@ -124,9 +124,9 @@ files:
 - lib/swarm_memory/optimization/analyzer.rb
 - lib/swarm_memory/optimization/defragmenter.rb
 - lib/swarm_memory/prompts/memory.md.erb
-- lib/swarm_memory/prompts/memory_assistant.md.erb
-- lib/swarm_memory/prompts/memory_researcher.md.erb
-- lib/swarm_memory/prompts/memory_retrieval.md.erb
+- lib/swarm_memory/prompts/memory_full_access.md.erb
+- lib/swarm_memory/prompts/memory_read_only.md.erb
+- lib/swarm_memory/prompts/memory_read_write.md.erb
 - lib/swarm_memory/search/semantic_search.rb
 - lib/swarm_memory/search/text_search.rb
 - lib/swarm_memory/search/text_similarity.rb
@@ -139,6 +139,7 @@ files:
 - lib/swarm_memory/tools/memory_glob.rb
 - lib/swarm_memory/tools/memory_grep.rb
 - lib/swarm_memory/tools/memory_read.rb
+- lib/swarm_memory/tools/memory_search.rb
 - lib/swarm_memory/tools/memory_write.rb
 - lib/swarm_memory/tools/title_lookup.rb
 - lib/swarm_memory/utils.rb