swarm_memory 2.2.2 → 2.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4216c2f9b10d9accb547d94709305359009d8b8a7440c3023c97d49cc66b5cd4
-  data.tar.gz: 670b1af5ec7880caa86fbceed37a030537cd863ec6a32155c144f706f1f96172
+  metadata.gz: 768a8a8cd1d0ab5a3edff5e6e0c54e3fdce1e6c6af281d6a39285019167b87c8
+  data.tar.gz: aa9e396d3c72e53bf49459828c635148205c523e6d16bb42e7f6e4e5856a1d4c
 SHA512:
-  metadata.gz: 747e338d2569036d590c783c674895fdb9420af52655e34a412605f4085ced7c0bc198bd70698df2c84689211846095e381622f6bbb139376c70e3d71b3e6871
-  data.tar.gz: bf9c87e64f5e149d7dbb00157abd6ba39f005e16cf29304382235c1ede975a13a76d1afc72ce12e83dfcec072610536a53e7abc457d8e0a7dff0061892e29759
+  metadata.gz: c35aad639f910180b0bcd73db10b8db18f4cb9bde3d136789e77b26ac1a1a2a66fc476b1cce9731bf06566ad8bf9bfbc8edfe0c513b62a303c79346c6efb5b52
+  data.tar.gz: 18f0c1c5fc97d2946174e43d61c86493cbaa31626a8c6ecbf019ad12ca9654ebdeb77475305a79fb1c11ed85eb85b35be44fad349bb56806e039ea6afafea247

data/lib/swarm_memory/core/semantic_index.rb

@@ -181,6 +181,9 @@ module SwarmMemory
 
       # Calculate hybrid scores combining semantic similarity and keyword matching
       #
+      # When keyword_score is 0 (no tag matches), falls back to pure semantic scoring
+      # to avoid penalizing results that have excellent semantic matches but no tag overlap.
+      #
       # @param results [Array<Hash>] Results with semantic :similarity scores
       # @param query_keywords [Array<String>] Keywords from query
       # @return [Array<Hash>] Results with updated :similarity (hybrid score) and debug info
@@ -189,8 +192,13 @@ module SwarmMemory
           semantic_score = result[:similarity]
           keyword_score = calculate_keyword_score(result, query_keywords)
 
-          # Hybrid score: weighted combination
-          hybrid_score = (@semantic_weight * semantic_score) + (@keyword_weight * keyword_score)
+          # Fallback to pure semantic when no keyword matches
+          # This prevents penalizing results with excellent semantic matches but no tag overlap
+          hybrid_score = if keyword_score.zero?
+            semantic_score
+          else
+            (@semantic_weight * semantic_score) + (@keyword_weight * keyword_score)
+          end
 
           # Update result with hybrid score and debug info
           result.merge(

data/lib/swarm_memory/core/storage.rb

@@ -18,7 +18,9 @@ module SwarmMemory
       #
       # @param adapter [Adapters::Base] Storage adapter
       # @param embedder [Embeddings::Embedder, nil] Optional embedder for semantic search
-      def initialize(adapter:, embedder: nil)
+      # @param semantic_weight [Float, nil] Weight for semantic similarity in hybrid search (0.0-1.0)
+      # @param keyword_weight [Float, nil] Weight for keyword matching in hybrid search (0.0-1.0)
+      def initialize(adapter:, embedder: nil, semantic_weight: nil, keyword_weight: nil)
         raise ArgumentError, "adapter is required" unless adapter.is_a?(Adapters::Base)
 
         @adapter = adapter
@@ -26,7 +28,10 @@ module SwarmMemory
 
         # Create semantic index if embedder is provided
         @semantic_index = if embedder
-          SemanticIndex.new(adapter: adapter, embedder: embedder)
+          index_options = { adapter: adapter, embedder: embedder }
+          index_options[:semantic_weight] = semantic_weight if semantic_weight
+          index_options[:keyword_weight] = keyword_weight if keyword_weight
+          SemanticIndex.new(**index_options)
         end
       end
 

data/lib/swarm_memory/dsl/memory_config.rb

@@ -84,6 +84,43 @@ module SwarmMemory
         @mode = value.to_sym
       end
 
+      # DSL method to set/get semantic weight for hybrid search
+      #
+      # Controls how much semantic (embedding) similarity affects search results.
+      # Default is 0.5 (50%). Set to 1.0 for pure semantic search.
+      #
+      # @param value [Float, nil] Weight between 0.0 and 1.0
+      # @return [Float, nil] Current semantic weight
+      #
+      # @example Pure semantic search (no keyword penalty)
+      #   semantic_weight 1.0
+      #   keyword_weight 0.0
+      def semantic_weight(value = nil)
+        if value.nil?
+          @adapter_options[:semantic_weight]
+        else
+          @adapter_options[:semantic_weight] = value.to_f
+        end
+      end
+
+      # DSL method to set/get keyword weight for hybrid search
+      #
+      # Controls how much keyword (tag) matching affects search results.
+      # Default is 0.5 (50%). Set to 0.0 to disable keyword matching.
+      #
+      # @param value [Float, nil] Weight between 0.0 and 1.0
+      # @return [Float, nil] Current keyword weight
+      #
+      # @example Disable keyword matching
+      #   keyword_weight 0.0
+      def keyword_weight(value = nil)
+        if value.nil?
+          @adapter_options[:keyword_weight]
+        else
+          @adapter_options[:keyword_weight] = value.to_f
+        end
+      end
+
       # Check if memory is enabled
       #
       # @return [Boolean] True if adapter is configured with required options

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -110,10 +110,12 @@ module SwarmMemory
           # MemoryConfig object (from DSL)
           [config.adapter_type, config.adapter_options]
         elsif config.is_a?(Hash)
-          # Hash (from YAML)
+          # Hash (from YAML) - symbolize keys for adapter compatibility
           adapter = (config[:adapter] || config["adapter"] || :filesystem).to_sym
-          options = config.reject { |k, _v| k == :adapter || k == "adapter" || k == :mode || k == "mode" }
-          [adapter, options]
+          options = config.reject { |k, _v| [:adapter, "adapter", :mode, "mode"].include?(k) }
+          # Symbolize keys so adapter receives keyword arguments correctly
+          symbolized_options = options.transform_keys { |k| k.to_s.to_sym }
+          [adapter, symbolized_options]
         else
           raise SwarmSDK::ConfigurationError, "Invalid memory configuration for #{agent_name}"
         end
@@ -125,7 +127,17 @@ module SwarmMemory
           raise SwarmSDK::ConfigurationError, "#{e.message} for agent #{agent_name}"
         end
 
-        # Instantiate adapter with options
+        # Extract hybrid search weights and other SDK-level config (before passing to adapter)
+        # Keys are already symbolized at this point
+        semantic_weight = adapter_options.delete(:semantic_weight)
+        keyword_weight = adapter_options.delete(:keyword_weight)
+
+        # Remove other SDK-level threshold configs that shouldn't go to adapter
+        adapter_options.delete(:discovery_threshold)
+        adapter_options.delete(:discovery_threshold_short)
+        adapter_options.delete(:adaptive_word_cutoff)
+
+        # Instantiate adapter with options (weights removed, adapter doesn't need them)
         # Note: Adapter is responsible for validating its own requirements
         begin
           adapter = adapter_class.new(**adapter_options)
@@ -137,8 +149,13 @@ module SwarmMemory
         # Create embedder for semantic search
         embedder = Embeddings::InformersEmbedder.new
 
-        # Create storage with embedder (enables semantic features)
-        Core::Storage.new(adapter: adapter, embedder: embedder)
+        # Create storage with embedder and hybrid search weights
+        Core::Storage.new(
+          adapter: adapter,
+          embedder: embedder,
+          semantic_weight: semantic_weight,
+          keyword_weight: keyword_weight,
+        )
       end
 
       # Parse memory configuration

data/lib/swarm_memory/tools/memory_glob.rb

@@ -138,7 +138,7 @@ module SwarmMemory
         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])})"
+          result << "- memory://#{entry[:path]} \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
         end
 
         output = result.join("\n")

data/lib/swarm_memory/tools/memory_grep.rb

@@ -7,6 +7,8 @@ module SwarmMemory
     # Searches content stored in memory entries using regex patterns.
     # Each agent has its own isolated memory storage.
     class MemoryGrep < RubyLLM::Tool
+      include TitleLookup
+
       description <<~DESC
         Search your memory content using regular expression patterns (like grep).
 
@@ -197,7 +199,7 @@ module SwarmMemory
         result = []
         result << "Memory entries matching #{search_desc} (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
         paths.each do |path|
-          result << "  memory://#{path}"
+          result << "- #{format_memory_path_with_title(path)}"
         end
         result.join("\n")
       end

data/lib/swarm_memory/tools/memory_read.rb

@@ -7,8 +7,10 @@ module SwarmMemory
     # Retrieves content stored by this agent using memory_write.
     # Each agent has its own isolated memory storage.
     class MemoryRead < RubyLLM::Tool
+      include TitleLookup
+
       description <<~DESC
-        Read content from your memory storage and retrieve all associated metadata.
+        Read content from your memory storage.
 
         REQUIRED: Provide the file_path parameter - the path to the memory entry you want to read.
 
@@ -25,9 +27,8 @@ module SwarmMemory
         INVALID: documentation/, reference/, tutorial/, parallel/, analysis/, notes/
 
         **Returns:**
-        JSON with two fields:
-        - content: Markdown content with line numbers (same format as Read tool)
-        - metadata: All metadata (title, type, tags, tools, permissions, confidence, etc.)
+        Markdown content with line numbers (same format as 'cat -n').
+        If the entry has related memories, a system-reminder section is appended listing them.
 
         **Examples:**
         - MemoryRead(file_path: "concept/ruby/classes.md") - Read a concept
@@ -38,6 +39,7 @@ module SwarmMemory
         - Always read entries before editing them with MemoryEdit
         - Line numbers in output are for reference only - don't include them when editing
         - Each read is tracked to enforce read-before-edit patterns
+        - Related memories in the system-reminder can be read with MemoryRead for additional context
       DESC
 
       param :file_path,
@@ -62,7 +64,7 @@ module SwarmMemory
       # Execute the tool
       #
       # @param file_path [String] Path to read from
-      # @return [String] JSON with content and metadata
+      # @return [String] Content with line numbers and optional related memories reminder
       def execute(file_path:)
         # Read full entry with metadata
         entry = @storage.read_entry(file_path: file_path)
@@ -70,8 +72,14 @@ module SwarmMemory
         # Register this read in the tracker with content digest
         Core::StorageReadTracker.register_read(@agent_name, file_path, entry.content)
 
-        # Always return JSON format (metadata always exists - at minimum title)
-        format_as_json(entry)
+        # Return plain text with line numbers
+        result = format_with_line_numbers(entry.content)
+
+        # Append related memories reminder if present
+        related_paths = entry.metadata&.dig("related") || []
+        result += format_related_memories_reminder(related_paths) if related_paths.any?
+
+        result
       rescue ArgumentError => e
         validation_error(e.message)
       end
@@ -82,29 +90,6 @@ module SwarmMemory
         "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
       end
 
-      # Format entry as JSON with content and metadata
-      #
-      # Returns a clean JSON format separating content from metadata.
-      # This prevents agents from mimicking metadata format when writing.
-      #
-      # Content includes line numbers (same format as Read tool).
-      # Metadata always includes at least title (from Entry).
-      # Additional metadata comes from the metadata hash (type, tags, tools, etc.)
-      #
-      # @param entry [Core::Entry] Entry with content and metadata
-      # @return [String] Pretty-printed JSON
-      def format_as_json(entry)
-        # Build metadata hash with title included
-        metadata_hash = { "title" => entry.title }
-        metadata_hash.merge!(entry.metadata) if entry.metadata
-
-        result = {
-          content: format_with_line_numbers(entry.content),
-          metadata: metadata_hash,
-        }
-        JSON.pretty_generate(result)
-      end
-
       # Format content with line numbers (same format as Read tool)
       #
       # @param content [String] Content to format
@@ -114,10 +99,29 @@ module SwarmMemory
         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}"
+          "#{line_number.to_s.rjust(6)} #{display_line}"
         end
         output_lines.join("\n")
       end
+
+      # Format related memories as a system-reminder section
+      #
+      # Looks up titles for each related memory path and formats
+      # them as a system reminder to help agents discover related content.
+      #
+      # @param related_paths [Array<String>] Array of memory paths (with or without memory:// prefix)
+      # @return [String] Formatted system-reminder section
+      def format_related_memories_reminder(related_paths)
+        lines = ["\n\n<system-reminder>"]
+        lines << "Related memories that may provide additional context:"
+
+        related_paths.each do |path|
+          lines << "- #{format_memory_path_with_title(path)}"
+        end
+
+        lines << "</system-reminder>"
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/swarm_memory/tools/title_lookup.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Tools
+    # Shared module for looking up memory entry titles
+    #
+    # Provides a consistent way to look up titles for memory entries
+    # across different tools (MemoryRead, MemoryGrep, etc.)
+    #
+    # @example Including in a tool
+    #   class MemoryGrep < RubyLLM::Tool
+    #     include TitleLookup
+    #
+    #     def some_method
+    #       title = lookup_title("concept/ruby/classes.md")
+    #     end
+    #   end
+    module TitleLookup
+      # Look up the title of a memory entry
+      #
+      # @param path [String] Path to the memory entry
+      # @return [String, nil] Title if found, nil otherwise
+      #
+      # @example
+      #   title = lookup_title("concept/ruby/classes.md")
+      #   # => "Ruby Classes"
+      def lookup_title(path)
+        entry = @storage.read_entry(file_path: path)
+        entry.title
+      rescue StandardError
+        nil
+      end
+
+      # Format a memory path with its title
+      #
+      # Normalizes the path (removes memory:// prefix if present) and
+      # formats it with the title in quotes if available.
+      #
+      # @param path [String] Path to the memory entry (with or without memory:// prefix)
+      # @return [String] Formatted string like 'memory://path "Title"' or 'memory://path'
+      #
+      # @example With title found
+      #   format_memory_path_with_title("concept/ruby/classes.md")
+      #   # => 'memory://concept/ruby/classes.md "Ruby Classes"'
+      #
+      # @example With memory:// prefix
+      #   format_memory_path_with_title("memory://concept/ruby/classes.md")
+      #   # => 'memory://concept/ruby/classes.md "Ruby Classes"'
+      #
+      # @example When title not found
+      #   format_memory_path_with_title("nonexistent.md")
+      #   # => 'memory://nonexistent.md'
+      def format_memory_path_with_title(path)
+        normalized_path = path.sub(%r{^memory://}, "")
+        title = lookup_title(normalized_path)
+
+        if title
+          "memory://#{normalized_path} \"#{title}\""
+        else
+          "memory://#{normalized_path}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_memory/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_memory
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.2.4
 platform: ruby
 authors:
 - Paulo Arruda
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.1
+        version: 2.5.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.1
+        version: 2.5.2
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -140,14 +140,15 @@ files:
 - lib/swarm_memory/tools/memory_grep.rb
 - lib/swarm_memory/tools/memory_read.rb
 - lib/swarm_memory/tools/memory_write.rb
+- lib/swarm_memory/tools/title_lookup.rb
 - lib/swarm_memory/utils.rb
 - lib/swarm_memory/version.rb
-homepage: https://github.com/parruda/claude-swarm
+homepage: https://github.com/parruda/swarm
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/parruda/claude-swarm
-  changelog_uri: https://github.com/parruda/claude-swarm/blob/main/docs/v2/CHANGELOG.swarm_memory.md
+  source_code_uri: https://github.com/parruda/swarm
+  changelog_uri: https://github.com/parruda/swarm/blob/main/docs/v2/CHANGELOG.swarm_memory.md
 rdoc_options: []
 require_paths:
 - lib