rcrewai 0.5.0 → 0.6.1

data/lib/rcrewai/memory/base_memory.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative '../similarity'
+require_relative 'in_memory_store'
+
+module RCrewAI
+  class Memory
+    # Shared behavior for the memory types: embed-on-write (when an embedder is
+    # present) and semantic recall with a lexical fallback when it isn't.
+    # Records are namespaced per (agent) scope + a type suffix so different
+    # memory types don't collide in a shared store.
+    class BaseMemory
+      def initialize(scope:, embedder: nil, store: nil, limit: nil)
+        @scope = "#{scope}:#{type_suffix}"
+        @embedder = embedder
+        @store = store || InMemoryStore.new
+        @limit = limit
+        @seq = 0
+      end
+
+      def record(text, metadata = {})
+        add(text, metadata)
+      end
+
+      def recall(query, limit: 3)
+        records = search_records(query, limit)
+        records.map { |r| format(r) }
+      end
+
+      def count
+        @store.all(scope: @scope).length
+      end
+
+      def clear!
+        @store.delete(scope: @scope)
+      end
+
+      protected
+
+      # Subclasses override to namespace their records.
+      def type_suffix
+        'base'
+      end
+
+      def format(record)
+        { text: record[:text], metadata: record[:metadata] }
+      end
+
+      def add(text, metadata)
+        vector = embed(text)
+        id = next_id(text)
+        @store.add(id: id, text: text, vector: vector, scope: @scope, metadata: stringify(metadata))
+        evict_if_needed
+        id
+      end
+
+      def search_records(query, limit)
+        all = @store.all(scope: @scope)
+        return [] if all.empty?
+
+        query_vector = embed(query)
+        if query_vector && all.any? { |r| r[:vector] }
+          @store.search(query_vector, k: limit, scope: @scope)
+        else
+          lexical_search(query, all, limit)
+        end
+      end
+
+      def lexical_search(query, records, limit)
+        records
+          .map { |r| [r, Similarity.lexical(query, r[:text])] }
+          .sort_by { |(_r, score)| -score }
+          .first(limit)
+          .map(&:first)
+      end
+
+      def embed(text)
+        return nil unless @embedder
+
+        @embedder.embed([text]).first
+      rescue StandardError
+        nil # embedding is best-effort; fall back to lexical
+      end
+
+      def evict_if_needed
+        return unless @limit
+
+        records = @store.all(scope: @scope)
+        return if records.length <= @limit
+
+        # records carry a monotonic :seq in metadata; drop the oldest.
+        oldest = records.min_by { |r| r[:metadata]['seq'].to_i }
+        @store.delete_record(id: oldest[:id], scope: @scope) if @store.respond_to?(:delete_record)
+      end
+
+      def next_id(text)
+        @seq += 1
+        Digest::SHA256.hexdigest("#{@scope}:#{@seq}:#{text}")[0, 24]
+      end
+
+      def stringify(metadata)
+        (metadata || {}).transform_keys(&:to_s).merge('seq' => @seq)
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/entity_memory.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'base_memory'
+
+module RCrewAI
+  class Memory
+    # Facts about entities (people, systems, concepts) accumulated from work.
+    # Entities are extracted heuristically (capitalized tokens / acronyms); an
+    # LLM-backed extractor can be swapped in later.
+    class EntityMemory < BaseMemory
+      # Skip sentence-initial common words that happen to be capitalized.
+      COMMON = %w[The A An I In On At To For Of With By And Or But It This That Who Where When].freeze
+
+      def initialize(scope:, embedder: nil, store: nil, limit: nil, extractor: nil)
+        super(scope: scope, embedder: embedder, store: store, limit: limit)
+        @extractor = extractor
+        @entities = []
+      end
+
+      # Records a full observation and indexes the entities it mentions.
+      def observe(text)
+        found = extract_entities(text)
+        @entities.concat(found)
+        add(text, { 'entities' => found })
+      end
+
+      def entities
+        @entities.uniq
+      end
+
+      protected
+
+      def type_suffix
+        'entity'
+      end
+
+      def format(record)
+        record[:text]
+      end
+
+      private
+
+      # Uses the custom extractor when provided, falling back to the heuristic
+      # if it's absent, returns nothing, or raises.
+      def extract_entities(text)
+        if @extractor
+          begin
+            result = Array(@extractor.call(text))
+            return result unless result.empty?
+          rescue StandardError
+            # fall through to heuristic
+          end
+        end
+        heuristic_entities(text)
+      end
+
+      def heuristic_entities(text)
+        text.to_s.scan(/\b([A-Z][a-zA-Z0-9]{1,})\b/).flatten.reject { |w| COMMON.include?(w) }.uniq
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/in_memory_store.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../similarity'
+
+module RCrewAI
+  class Memory
+    # Default, volatile vector store: records live in a Hash keyed by scope.
+    # Records: { id:, text:, vector:, metadata: }. Cosine search in Ruby.
+    class InMemoryStore
+      def initialize
+        @scopes = Hash.new { |h, k| h[k] = {} }
+      end
+
+      def add(id:, text:, vector:, scope:, metadata: {})
+        @scopes[scope][id] = { id: id, text: text, vector: vector, metadata: metadata || {} }
+      end
+
+      def all(scope:)
+        @scopes[scope].values
+      end
+
+      def search(vector, k:, scope:)
+        @scopes[scope].values
+                      .reject { |r| r[:vector].nil? }
+                      .map { |r| [r, Similarity.cosine(vector, r[:vector])] }
+                      .sort_by { |(_r, score)| -score }
+                      .first(k)
+                      .map(&:first)
+      end
+
+      def delete(scope:)
+        @scopes.delete(scope)
+      end
+
+      def delete_record(id:, scope:)
+        @scopes[scope].delete(id)
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/llm_entity_extractor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../output_schema'
+
+module RCrewAI
+  class Memory
+    # Extracts named entities from text with an LLM. Pass an instance as the
+    # `extractor:` for EntityMemory. Responds to `call(text) -> [names]`.
+    # Returns [] on any parse/LLM failure so EntityMemory falls back to the
+    # heuristic extractor — extraction is best-effort and never fatal.
+    class LlmEntityExtractor
+      PROMPT = <<~PROMPT
+        Extract the named entities (people, organizations, systems, products,
+        places, and key concepts) from the text below. Respond ONLY with a JSON
+        array of strings, e.g. ["Alice", "Payments", "Redis"]. No prose.
+
+        Text:
+      PROMPT
+
+      def initialize(llm)
+        @llm = llm
+      end
+
+      def call(text)
+        response = @llm.chat(messages: [{ role: 'user', content: "#{PROMPT}#{text}" }])
+        content = response.is_a?(Hash) ? response[:content] : response
+        parsed = OutputSchema.parse(content.to_s)
+        parsed.is_a?(Array) ? parsed.map(&:to_s) : []
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/long_term_memory.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'base_memory'
+
+module RCrewAI
+  class Memory
+    # Durable insights promoted from successful executions. Dedupes
+    # near-identical insights so the store doesn't fill with paraphrases.
+    class LongTermMemory < BaseMemory
+      DEDUPE_THRESHOLD = 0.92
+
+      def record(text, metadata = {})
+        return nil if duplicate?(text)
+
+        add(text, metadata)
+      end
+
+      protected
+
+      def type_suffix
+        'long_term'
+      end
+
+      private
+
+      def duplicate?(text)
+        existing = @store.all(scope: @scope)
+        return false if existing.empty?
+
+        query_vector = embed(text)
+        if query_vector && existing.any? { |r| r[:vector] }
+          existing.any? { |r| r[:vector] && Similarity.cosine(query_vector, r[:vector]) >= DEDUPE_THRESHOLD }
+        else
+          existing.any? { |r| Similarity.lexical(text, r[:text]) >= DEDUPE_THRESHOLD }
+        end
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/short_term_memory.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base_memory'
+
+module RCrewAI
+  class Memory
+    # Recent executions with semantic recall. Capped and volatile-by-default.
+    class ShortTermMemory < BaseMemory
+      def initialize(scope:, embedder: nil, store: nil, limit: 100)
+        super
+      end
+
+      protected
+
+      def type_suffix
+        'short_term'
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/sqlite_store.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../similarity'
+
+module RCrewAI
+  class Memory
+    # Persistent vector store backed by SQLite. Vectors are packed as
+    # little-endian floats; metadata is JSON. Cosine is computed in Ruby over
+    # rows filtered by scope — adequate for the thousands-of-memories scale an
+    # agent produces; an ANN index is a later optimization.
+    #
+    # The sqlite3 gem is required lazily so the rest of the library (and the
+    # in-memory store) works even if it isn't installed.
+    class SqliteStore
+      DEFAULT_PATH = File.join(Dir.home, '.rcrewai', 'memory.db')
+
+      # max_candidates bounds how many (most-recent) rows a search cosines, so
+      # recall cost stays constant as total memory grows. nil = consider all.
+      def initialize(path: DEFAULT_PATH, max_candidates: 1000)
+        require 'sqlite3'
+        ensure_parent_dir(path) unless path == ':memory:'
+        @db = SQLite3::Database.new(path)
+        @db.results_as_hash = true
+        @max_candidates = max_candidates
+        create_schema
+      end
+
+      def add(id:, text:, vector:, scope:, metadata: {})
+        @db.execute(
+          'INSERT INTO memories (id, scope, text, vector, metadata) VALUES (?, ?, ?, ?, ?) ' \
+          'ON CONFLICT(id) DO UPDATE SET scope=excluded.scope, text=excluded.text, ' \
+          'vector=excluded.vector, metadata=excluded.metadata',
+          [id, scope, text, pack_vector(vector), JSON.generate(metadata || {})]
+        )
+      end
+
+      def all(scope:)
+        @db.execute('SELECT * FROM memories WHERE scope = ?', [scope]).map { |row| to_record(row) }
+      end
+
+      def search(vector, k:, scope:)
+        candidates(scope)
+          .reject { |r| r[:vector].nil? }
+          .map { |r| [r, Similarity.cosine(vector, r[:vector])] }
+          .sort_by { |(_r, score)| -score }
+          .first(k)
+          .map(&:first)
+      end
+
+      def delete(scope:)
+        @db.execute('DELETE FROM memories WHERE scope = ?', [scope])
+      end
+
+      def delete_record(id:, scope:)
+        @db.execute('DELETE FROM memories WHERE id = ? AND scope = ?', [id, scope])
+      end
+
+      private
+
+      # The rows a search will consider: the most-recent @max_candidates within
+      # the scope (rowid tracks insertion order). Bounds cosine cost at scale.
+      def candidates(scope)
+        sql = 'SELECT * FROM memories WHERE scope = ? ORDER BY rowid DESC'
+        params = [scope]
+        if @max_candidates
+          sql += ' LIMIT ?'
+          params << @max_candidates
+        end
+        @db.execute(sql, params).map { |row| to_record(row) }
+      end
+
+      def create_schema
+        @db.execute(<<~SQL)
+          CREATE TABLE IF NOT EXISTS memories (
+            id TEXT PRIMARY KEY,
+            scope TEXT NOT NULL,
+            text TEXT,
+            vector BLOB,
+            metadata TEXT,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP
+          )
+        SQL
+        @db.execute('CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories (scope)')
+      end
+
+      def ensure_parent_dir(path)
+        require 'fileutils'
+        FileUtils.mkdir_p(File.dirname(path))
+      end
+
+      def pack_vector(vector)
+        return nil if vector.nil?
+
+        vector.map(&:to_f).pack('e*')
+      end
+
+      def unpack_vector(blob)
+        return nil if blob.nil?
+
+        blob.unpack('e*')
+      end
+
+      def to_record(row)
+        {
+          id: row['id'],
+          text: row['text'],
+          vector: unpack_vector(row['vector']),
+          metadata: JSON.parse(row['metadata'] || '{}')
+        }
+      end
+    end
+  end
+end

data/lib/rcrewai/memory/tool_memory.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base_memory'
+
+module RCrewAI
+  class Memory
+    # Tool-call history and outcomes. Replaces the old @tool_usage array;
+    # persistable and searchable like the other memory types.
+    class ToolMemory < BaseMemory
+      def record_call(tool_name, params, result)
+        success = !result.to_s.downcase.include?('error')
+        text = "#{tool_name}(#{format_params(params)}) -> #{result}"
+        add(text, { 'tool' => tool_name, 'success' => success, 'result' => result.to_s })
+      end
+
+      # Most-recent-first usage records for a given tool.
+      def usage_for(tool_name, limit: 5)
+        @store.all(scope: @scope)
+              .select { |r| r[:metadata]['tool'] == tool_name }
+              .sort_by { |r| -r[:metadata]['seq'].to_i }
+              .first(limit)
+              .map { |r| r[:text] }
+      end
+
+      protected
+
+      def type_suffix
+        'tool'
+      end
+
+      private
+
+      def format_params(params)
+        (params || {}).map { |k, v| "#{k}=#{v}" }.join(', ')
+      end
+    end
+  end
+end