rcrewai 0.4.0 → 0.6.0

data/lib/rcrewai/memory.rb

@@ -1,202 +1,99 @@
 # frozen_string_literal: true
 
 require 'json'
-require 'digest'
 
 module RCrewAI
+  # Cognitive memory facade. Preserves the original public API
+  # (add_execution / add_tool_usage / relevant_executions / tool_usage_for /
+  # clear_*! / stats) while delegating to semantic, optionally-persistent
+  # memory types (short-term, long-term, entity, tool).
+  #
+  # Zero-config: `Memory.new` uses an in-memory store and, when no embedder is
+  # available, falls back to lexical similarity — so existing code behaves as
+  # before, just with better recall once an embedder is configured.
   class Memory
-    attr_reader :short_term, :long_term, :tool_usage
-
-    def initialize
-      @short_term = []  # Recent executions, limited size
-      @long_term = {}   # Persistent memory, keyed by task type/similarity
-      @tool_usage = []  # Tool usage history
-      @max_short_term = 100
-      @similarity_threshold = 0.7
+    def initialize(scope: 'default', embedder: nil, store: nil, short_term_limit: 100)
+      @short_term = ShortTermMemory.new(scope: scope, embedder: embedder, store: store, limit: short_term_limit)
+      @long_term  = LongTermMemory.new(scope: scope, embedder: embedder, store: store)
+      @entity     = EntityMemory.new(scope: scope, embedder: embedder, store: store)
+      @tool       = ToolMemory.new(scope: scope, embedder: embedder, store: store)
     end
 
+    # --- original API --------------------------------------------------------
+
     def add_execution(task, result, execution_time)
-      execution_data = {
-        task_name: task.name,
-        task_description: task.description,
-        task_type: classify_task_type(task),
-        result: result,
-        execution_time: execution_time,
-        timestamp: Time.now,
-        success: !result.to_s.downcase.include?('failed'),
-        hash: generate_task_hash(task)
+      success = !result.to_s.downcase.include?('failed')
+      text = "Task: #{task.name}\nDescription: #{task.description}\nResult: #{truncate(result, 300)}"
+      metadata = {
+        'task' => task.name,
+        'success' => success,
+        'execution_time' => execution_time,
+        'result' => result.to_s
       }
 
-      # Add to short-term memory
-      @short_term.unshift(execution_data)
-      @short_term = @short_term.first(@max_short_term)
-
-      # Add to long-term memory if successful
-      return unless execution_data[:success]
-
-      task_type = execution_data[:task_type]
-      @long_term[task_type] ||= []
-      @long_term[task_type] << execution_data
-
-      # Keep only best executions for each type
-      @long_term[task_type] = @long_term[task_type]
-                              .sort_by { |e| [e[:success] ? 0 : 1, -e[:execution_time]] }
-                              .first(10)
+      @short_term.record(text, metadata)
+      if success
+        @long_term.record(text, metadata)
+        @entity.observe("#{task.description} #{result}")
+      end
+      nil
     end
 
     def add_tool_usage(tool_name, params, result)
-      usage_data = {
-        tool_name: tool_name,
-        params: params,
-        result: result,
-        timestamp: Time.now,
-        success: !result.to_s.downcase.include?('error')
-      }
-
-      @tool_usage.unshift(usage_data)
-      @tool_usage = @tool_usage.first(50) # Keep last 50 tool usages
+      @tool.record_call(tool_name, params, result)
+      nil
     end
 
+    # Returns a formatted string of the most relevant past executions, or nil.
     def relevant_executions(task, limit = 3)
-      task_type = classify_task_type(task)
-      task_hash = generate_task_hash(task)
-
-      # Get similar executions from both short and long term memory
-      candidates = []
-
-      # Check short-term for exact or similar matches
-      @short_term.each do |execution|
-        if execution[:hash] == task_hash
-          candidates << { execution: execution, similarity: 1.0 }
-        elsif execution[:task_type] == task_type
-          similarity = calculate_similarity(task, execution)
-          candidates << { execution: execution, similarity: similarity } if similarity > @similarity_threshold
-        end
-      end
+      query = "#{task.name} #{task.description}"
+      recalled = (@short_term.recall(query, limit: limit) + @long_term.recall(query, limit: limit))
+      seen = {}
+      unique = recalled.reject { |r| seen[r[:text]].tap { seen[r[:text]] = true } }
+      return nil if unique.empty?
 
-      # Check long-term memory
-      @long_term[task_type]&.each do |execution|
-        similarity = calculate_similarity(task, execution)
-        candidates << { execution: execution, similarity: similarity } if similarity > @similarity_threshold
-      end
-
-      # Sort by similarity and success, return top results
-      relevant = candidates
-                 .sort_by { |c| [-c[:similarity], c[:execution][:success] ? 0 : 1] }
-                 .first(limit)
-                 .map { |c| format_execution_for_context(c[:execution]) }
-
-      relevant.empty? ? nil : relevant.join("\n---\n")
+      unique.first(limit).map { |r| format_execution(r) }.join("\n---\n")
     end
 
     def tool_usage_for(tool_name, limit = 5)
-      @tool_usage
-        .select { |usage| usage[:tool_name] == tool_name }
-        .first(limit)
-        .map { |usage| format_tool_usage_for_context(usage) }
-        .join("\n")
+      @tool.usage_for(tool_name, limit: limit).join("\n")
     end
 
     def clear_short_term!
-      @short_term.clear
+      @short_term.clear!
     end
 
     def clear_all!
-      @short_term.clear
-      @long_term.clear
-      @tool_usage.clear
+      @short_term.clear!
+      @long_term.clear!
+      @entity.clear!
+      @tool.clear!
     end
 
     def stats
       {
-        short_term_count: @short_term.length,
-        long_term_types: @long_term.keys.length,
-        long_term_total: @long_term.values.flatten.length,
-        tool_usage_count: @tool_usage.length,
-        success_rate: calculate_success_rate
+        short_term_count: @short_term.count,
+        long_term_total: @long_term.count,
+        entity_count: @entity.entities.length,
+        tool_usage_count: @tool.count
       }
     end
 
-    private
-
-    def classify_task_type(task)
-      description = task.description.downcase
-
-      if description.include?('research') || description.include?('find') || description.include?('search')
-        return :research
-      end
-      if description.include?('analyze') || description.include?('examine') || description.include?('study')
-        return :analysis
-      end
-      if description.include?('write') || description.include?('create') || description.include?('compose')
-        return :writing
-      end
-      if description.include?('code') || description.include?('program') || description.include?('develop')
-        return :coding
-      end
-      if description.include?('plan') || description.include?('strategy') || description.include?('organize')
-        return :planning
-      end
-
-      :general
-    end
-
-    def generate_task_hash(task)
-      content = "#{task.name}:#{task.description}"
-      Digest::SHA256.hexdigest(content)[0..16]
-    end
-
-    def calculate_similarity(task, execution)
-      # Simple similarity based on common words and task type
-      task_words = extract_keywords(task.description)
-      execution_words = extract_keywords(execution[:task_description])
-
-      common_words = (task_words & execution_words).length
-      total_words = (task_words | execution_words).length
-
-      return 0.0 if total_words.zero?
+    # --- new surface (optional direct access) --------------------------------
 
-      word_similarity = common_words.to_f / total_words
+    attr_reader :short_term, :long_term, :entity, :tool
 
-      # Boost similarity if task types match
-      type_bonus = classify_task_type(task) == execution[:task_type] ? 0.2 : 0.0
-
-      [word_similarity + type_bonus, 1.0].min
-    end
-
-    def extract_keywords(text)
-      # Simple keyword extraction - remove common words
-      stopwords = %w[the a an and or but in on at to for of with by]
-      text.downcase.split(/\W+/).reject { |w| w.length < 3 || stopwords.include?(w) }
-    end
-
-    def format_execution_for_context(execution)
-      success_indicator = execution[:success] ? '✓' : '✗'
-      <<~CONTEXT
-        #{success_indicator} Task: #{execution[:task_name]}
-        Description: #{execution[:task_description]}
-        Result: #{execution[:result][0..200]}#{'...' if execution[:result].length > 200}
-        Time: #{execution[:execution_time].round(2)}s
-        Date: #{execution[:timestamp].strftime('%Y-%m-%d %H:%M')}
-      CONTEXT
-    end
+    private
 
-    def format_tool_usage_for_context(usage)
-      success_indicator = usage[:success] ? '✓' : '✗'
-      params_str = usage[:params].map { |k, v| "#{k}=#{v}" }.join(', ')
-      <<~CONTEXT
-        #{success_indicator} Tool: #{usage[:tool_name]}
-        Params: #{params_str}
-        Result: #{usage[:result][0..100]}#{'...' if usage[:result].to_s.length > 100}
-        Date: #{usage[:timestamp].strftime('%Y-%m-%d %H:%M')}
-      CONTEXT
+    def format_execution(record)
+      meta = record[:metadata] || {}
+      indicator = meta['success'] == false ? '✗' : '✓'
+      "#{indicator} #{record[:text]}"
     end
 
-    def calculate_success_rate
-      return 0.0 if @short_term.empty?
-
-      successful = @short_term.count { |e| e[:success] }
-      (successful.to_f / @short_term.length * 100).round(1)
+    def truncate(text, limit)
+      str = text.to_s
+      str.length > limit ? "#{str[0, limit]}..." : str
     end
   end
 end

data/lib/rcrewai/multimodal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module RCrewAI
+  # Builds multimodal message content (text + images) in the OpenAI
+  # chat-completions format:
+  #   [{ type: 'text', text: '...' },
+  #    { type: 'image_url', image_url: { url: '...' } }]
+  #
+  # Local image paths are base64-encoded into data URLs; URLs pass through.
+  # Only OpenAI-style multimodal is supported today; other providers raise.
+  module Multimodal
+    SUPPORTED_PROVIDERS = %i[openai azure].freeze
+
+    MIME_TYPES = {
+      '.png' => 'image/png',
+      '.jpg' => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif' => 'image/gif',
+      '.webp' => 'image/webp'
+    }.freeze
+
+    module_function
+
+    # Returns an OpenAI-style content-parts array for the given text and
+    # attachments. With no attachments this is a single text part.
+    def content_parts(text, attachments)
+      parts = [{ type: 'text', text: text.to_s }]
+      Array(attachments).each { |att| parts << image_part(att) }
+      parts
+    end
+
+    def supported_provider?(provider)
+      SUPPORTED_PROVIDERS.include?(provider.to_sym)
+    end
+
+    def ensure_supported_provider!(provider)
+      return if supported_provider?(provider)
+
+      raise UnsupportedProviderError,
+            "multimodal attachments are not supported for provider #{provider}"
+    end
+
+    def image_part(attachment)
+      type = attachment[:type] || attachment['type']
+      raise UnsupportedAttachmentError, "unsupported attachment type: #{type.inspect}" unless type.to_sym == :image
+
+      url = attachment[:url] || attachment['url']
+      path = attachment[:path] || attachment['path']
+      resolved = url || data_url_for(path)
+
+      { type: 'image_url', image_url: { url: resolved } }
+    end
+
+    def data_url_for(path)
+      raise UnsupportedAttachmentError, 'image attachment needs a :url or :path' unless path
+
+      mime = MIME_TYPES[File.extname(path).downcase] || 'application/octet-stream'
+      encoded = Base64.strict_encode64(File.binread(path))
+      "data:#{mime};base64,#{encoded}"
+    end
+
+    class UnsupportedAttachmentError < RCrewAI::Error; end
+    class UnsupportedProviderError < RCrewAI::Error; end
+  end
+end

data/lib/rcrewai/rate_limiter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  # Thread-safe requests-per-minute throttle. Records call timestamps in a
+  # rolling 60-second window; `acquire` blocks (sleeps) until a slot is free.
+  #
+  # The clock and sleeper are injectable so tests can drive time deterministically
+  # without touching the wall clock. `max_rpm` of nil or 0 means unlimited.
+  class RateLimiter
+    WINDOW = 60.0
+
+    def initialize(max_rpm:, clock: nil, sleeper: nil)
+      @max_rpm = max_rpm
+      @clock = clock || -> { current_time }
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @calls = []
+      @mutex = Mutex.new
+    end
+
+    # Blocks until making a call would keep us within max_rpm, then records it.
+    def acquire
+      return record_unlimited if unlimited?
+
+      loop do
+        wait = @mutex.synchronize do
+          prune(@clock.call)
+          if @calls.length < @max_rpm
+            @calls << @clock.call
+            return
+          end
+          # Time until the oldest in-window call ages out.
+          (@calls.first + WINDOW) - @clock.call
+        end
+
+        @sleeper.call(wait) if wait.positive?
+      end
+    end
+
+    # Number of calls currently inside the window (useful for tests/metrics).
+    def recent_count
+      @mutex.synchronize do
+        prune(@clock.call)
+        @calls.length
+      end
+    end
+
+    private
+
+    def unlimited?
+      @max_rpm.nil? || @max_rpm.zero?
+    end
+
+    def record_unlimited
+      @mutex.synchronize { @calls << @clock.call }
+      nil
+    end
+
+    def prune(now)
+      cutoff = now - WINDOW
+      @calls.reject! { |t| t <= cutoff }
+    end
+
+    def current_time
+      # Fully-qualified: bare `Process` would resolve to RCrewAI::Process here.
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    # Wraps an LLM client so every #chat acquires a rate-limiter slot first.
+    # All other messages delegate to the wrapped client unchanged.
+    class ThrottledClient
+      def initialize(client, limiter)
+        @client = client
+        @limiter = limiter
+      end
+
+      def chat(**kwargs, &block)
+        @limiter.acquire
+        @client.chat(**kwargs, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private)
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        if @client.respond_to?(name)
+          @client.public_send(name, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rcrewai/similarity.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  # Similarity measures shared across Knowledge and Memory. `cosine` compares
+  # embedding vectors; `lexical` is the word-overlap fallback used when no
+  # embedder is available.
+  module Similarity
+    STOPWORDS = %w[the a an and or but in on at to for of with by is are was were be].freeze
+
+    module_function
+
+    def cosine(vec_a, vec_b)
+      dot = 0.0
+      norm_a = 0.0
+      norm_b = 0.0
+      length = [vec_a.length, vec_b.length].max
+      length.times do |i|
+        ai = (vec_a[i] || 0).to_f
+        bi = (vec_b[i] || 0).to_f
+        dot += ai * bi
+        norm_a += ai * ai
+        norm_b += bi * bi
+      end
+      return 0.0 if norm_a.zero? || norm_b.zero?
+
+      dot / (Math.sqrt(norm_a) * Math.sqrt(norm_b))
+    end
+
+    # Jaccard-style overlap of content words. Cheap, no embeddings.
+    def lexical(text_a, text_b)
+      words_a = keywords(text_a)
+      words_b = keywords(text_b)
+      union = (words_a | words_b).length
+      return 0.0 if union.zero?
+
+      (words_a & words_b).length.to_f / union
+    end
+
+    def keywords(text)
+      text.to_s.downcase.split(/\W+/).reject { |w| w.length < 3 || STOPWORDS.include?(w) }
+    end
+  end
+end

data/lib/rcrewai/task.rb

@@ -9,7 +9,7 @@ module RCrewAI
     include AsyncExtensions
     include HumanInteractionExtensions
     attr_reader :name, :description, :agent, :context, :expected_output, :tools, :async,
-                :raw_result, :structured_output
+                :raw_result, :structured_output, :attachments
     attr_accessor :result, :status, :start_time, :end_time, :execution_time
 
     def initialize(name:, description:, agent: nil, **options)
@@ -21,6 +21,7 @@ module RCrewAI
       @tools = options[:tools] || []      # Additional tools for this specific task
       @async = options[:async] || false   # Whether task can run asynchronously
       @callback = options[:callback]      # Callback function after completion
+      @attachments = options[:attachments] || [] # Multimodal inputs (images)
 
       # Output processing (0.4.0)
       @output_schema = options[:output_schema]            # JSON-schema for structured output

data/lib/rcrewai/tool_runner.rb

@@ -27,7 +27,7 @@ module RCrewAI
         emit(Events::IterationStart, iteration: iter, iteration_index: iter)
 
         response = @llm.chat(
-          messages: msgs,
+          messages: fit_context(msgs),
           tools: @tools.map(&:json_schema),
           stream: ->(e) { @sink.call(retag(e, iter)) }
         )
@@ -80,6 +80,12 @@ module RCrewAI
 
     private
 
+    # Trims the message list to the model's context window when the agent
+    # supports it; a no-op otherwise.
+    def fit_context(messages)
+      @agent.respond_to?(:fit_context) ? @agent.fit_context(messages) : messages
+    end
+
     def tool_result_message(call_id, content)
       { role: 'tool', tool_call_id: call_id, content: content }
     end

data/lib/rcrewai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RCrewAI
-  VERSION = '0.4.0'
+  VERSION = '0.6.0'
 end

data/lib/rcrewai.rb

@@ -22,7 +22,18 @@ require_relative 'rcrewai/events'
 require_relative 'rcrewai/sse_parser'
 require_relative 'rcrewai/pricing'
 require_relative 'rcrewai/llm_client'
+require_relative 'rcrewai/similarity'
 require_relative 'rcrewai/memory'
+require_relative 'rcrewai/memory/in_memory_store'
+require_relative 'rcrewai/memory/sqlite_store'
+require_relative 'rcrewai/memory/base_memory'
+require_relative 'rcrewai/memory/short_term_memory'
+require_relative 'rcrewai/memory/long_term_memory'
+require_relative 'rcrewai/memory/entity_memory'
+require_relative 'rcrewai/memory/tool_memory'
+require_relative 'rcrewai/rate_limiter'
+require_relative 'rcrewai/context_window'
+require_relative 'rcrewai/multimodal'
 require_relative 'rcrewai/knowledge'
 require_relative 'rcrewai/human_input'
 require_relative 'rcrewai/tool_schema'

data/rcrewai.gemspec

@@ -59,6 +59,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'nokogiri', '~> 1.15'
   spec.add_dependency 'pdf-reader', '~> 2.11'
   spec.add_dependency 'ruby-openai', '~> 6.3'
+  spec.add_dependency 'sqlite3', '~> 2.0'
   spec.add_dependency 'thor', '~> 1.3'
 
   # Development dependencies

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcrewai
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - gkosmo
@@ -149,6 +149,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -342,6 +356,7 @@ files:
 - docs/mcp.md
 - docs/superpowers/plans/2026-05-11-llm-modernization.md
 - docs/superpowers/specs/2026-05-11-llm-modernization-design.md
+- docs/superpowers/specs/2026-07-06-cognitive-memory-design.md
 - docs/tutorials/advanced-agents.md
 - docs/tutorials/custom-tools.md
 - docs/tutorials/deployment.md
@@ -349,17 +364,26 @@ files:
 - docs/tutorials/index.md
 - docs/tutorials/multiple-crews.md
 - docs/upgrading-to-0.3.md
+- docs/upgrading-to-0.4.md
+- docs/upgrading-to-0.6.md
 - examples/async_execution_example.rb
+- examples/cognitive_memory_example.rb
+- examples/flow_example.rb
 - examples/hierarchical_crew_example.rb
 - examples/human_in_the_loop_example.rb
+- examples/knowledge_rag_example.rb
 - examples/mcp_example.rb
 - examples/native_tools_example.rb
+- examples/planning_and_training_example.rb
 - examples/streaming_example.rb
+- examples/structured_output_example.rb
 - lib/rcrewai.rb
 - lib/rcrewai/agent.rb
+- lib/rcrewai/agent_augmentations.rb
 - lib/rcrewai/async_executor.rb
 - lib/rcrewai/cli.rb
 - lib/rcrewai/configuration.rb
+- lib/rcrewai/context_window.rb
 - lib/rcrewai/crew.rb
 - lib/rcrewai/events.rb
 - lib/rcrewai/flow.rb
@@ -386,11 +410,21 @@ files:
 - lib/rcrewai/mcp/transport/http.rb
 - lib/rcrewai/mcp/transport/stdio.rb
 - lib/rcrewai/memory.rb
+- lib/rcrewai/memory/base_memory.rb
+- lib/rcrewai/memory/entity_memory.rb
+- lib/rcrewai/memory/in_memory_store.rb
+- lib/rcrewai/memory/long_term_memory.rb
+- lib/rcrewai/memory/short_term_memory.rb
+- lib/rcrewai/memory/sqlite_store.rb
+- lib/rcrewai/memory/tool_memory.rb
+- lib/rcrewai/multimodal.rb
 - lib/rcrewai/output_schema.rb
 - lib/rcrewai/planning.rb
 - lib/rcrewai/pricing.rb
 - lib/rcrewai/process.rb
 - lib/rcrewai/provider_schema.rb
+- lib/rcrewai/rate_limiter.rb
+- lib/rcrewai/similarity.rb
 - lib/rcrewai/sse_parser.rb
 - lib/rcrewai/task.rb
 - lib/rcrewai/tool_runner.rb