igniter 0.4.5 → 0.5.1

data/packages/igniter-core/lib/igniter/core/memory/store.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Abstract base class defining the Store interface for episodic memory.
+    #
+    # Concrete adapters must subclass Store and implement all public methods.
+    # All methods raise +NotImplementedError+ by default.
+    #
+    # == Interface
+    #
+    #   store.record(agent_id:, type:, content:)             # => Episode
+    #   store.episodes(agent_id:, last: 50)                  # => Array<Episode>
+    #   store.retrieve(agent_id:, query: "keyword")          # => Array<Episode>
+    #   store.store_fact(agent_id:, key:, value:)
+    #   store.facts(agent_id:)                               # => Hash{key => Fact}
+    #   store.record_reflection(agent_id:, summary:)         # => ReflectionRecord
+    #   store.reflections(agent_id:)                         # => Array<ReflectionRecord>
+    #   store.apply_reflection(id:)                          # => true/false
+    #   store.clear(agent_id:)
+    class Store
+      # Record an episode. Returns the persisted Episode.
+      #
+      # @param agent_id  [String]         identifier of the owning agent
+      # @param type      [String, Symbol]  category tag for the episode
+      # @param content   [String]          textual description of the event
+      # @param session_id [String, nil]    optional session grouping key
+      # @param outcome   [String, nil]     result label, e.g. "success"/"failure"
+      # @param importance [Float]          relevance weight 0.0-1.0 (default 0.5)
+      # @return [Episode]
+      def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists
+        raise NotImplementedError, "#{self.class}#record not implemented"
+      end
+
+      # Return episodes for an agent, newest last.
+      #
+      # @param agent_id [String]         identifier of the agent
+      # @param last     [Integer]        maximum number of episodes to return
+      # @param type     [String, Symbol, nil] optional type filter
+      # @return [Array<Episode>]
+      def episodes(agent_id:, last: 50, type: nil)
+        raise NotImplementedError, "#{self.class}#episodes not implemented"
+      end
+
+      # Keyword-search episodes. Returns Array<Episode>.
+      #
+      # When +query+ is nil, returns the last +limit+ episodes.
+      # When +query+ is provided, filters by case-insensitive substring or FTS match.
+      #
+      # @param agent_id [String]
+      # @param query    [String, nil] search term
+      # @param limit    [Integer]     maximum results (default 10)
+      # @param type     [String, Symbol, nil] optional type filter
+      # @return [Array<Episode>]
+      def retrieve(agent_id:, query: nil, limit: 10, type: nil)
+        raise NotImplementedError, "#{self.class}#retrieve not implemented"
+      end
+
+      # Upsert a fact for an agent.
+      #
+      # @param agent_id   [String]  identifier of the owning agent
+      # @param key        [String]  fact name
+      # @param value      [Object]  fact value
+      # @param confidence [Float]   confidence score 0.0-1.0 (default 1.0)
+      # @return [Fact]
+      def store_fact(agent_id:, key:, value:, confidence: 1.0)
+        raise NotImplementedError, "#{self.class}#store_fact not implemented"
+      end
+
+      # Returns all facts for an agent as a Hash keyed by string key.
+      #
+      # @param agent_id [String]
+      # @return [Hash{String => Fact}]
+      def facts(agent_id:)
+        raise NotImplementedError, "#{self.class}#facts not implemented"
+      end
+
+      # Store a reflection record. Returns the persisted ReflectionRecord.
+      #
+      # @param agent_id    [String]      owning agent identifier
+      # @param summary     [String]      human-readable reflection summary
+      # @param system_patch [String, nil] optional suggested system prompt patch
+      # @param applied     [Boolean]     whether already applied (default false)
+      # @return [ReflectionRecord]
+      def record_reflection(agent_id:, summary:, system_patch: nil, applied: false)
+        raise NotImplementedError, "#{self.class}#record_reflection not implemented"
+      end
+
+      # Returns reflection records for an agent.
+      #
+      # @param agent_id [String]
+      # @param applied  [Boolean, nil] nil returns all; true/false filters by applied flag
+      # @return [Array<ReflectionRecord>]
+      def reflections(agent_id:, applied: nil)
+        raise NotImplementedError, "#{self.class}#reflections not implemented"
+      end
+
+      # Mark a reflection as applied.
+      #
+      # @param id [Integer] reflection identifier
+      # @return [Boolean] true if found and updated, false if not found
+      def apply_reflection(id:)
+        raise NotImplementedError, "#{self.class}#apply_reflection not implemented"
+      end
+
+      # Clear all stored data for an agent.
+      #
+      # @param agent_id [String]
+      # @return [void]
+      def clear(agent_id:)
+        raise NotImplementedError, "#{self.class}#clear not implemented"
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/stores/in_memory.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    module Stores
+      # Thread-safe in-memory implementation of the Store interface.
+      #
+      # Stores all data in process memory. Suitable for testing and
+      # single-process applications where persistence is not required.
+      # All operations are protected by a single Mutex for thread safety.
+      #
+      # @example
+      #   store = Igniter::Memory::Stores::InMemory.new
+      #   ep    = store.record(agent_id: "bot:1", type: :tool_call, content: "searched web")
+      #   store.episodes(agent_id: "bot:1") # => [ep]
+      class InMemory < Store
+        def initialize # rubocop:disable Lint/MissingSuper
+          @episodes    = []
+          @facts       = {}
+          @reflections = []
+          @seq         = 0
+          @mutex       = Mutex.new
+        end
+
+        # @see Store#record
+        def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+          @mutex.synchronize do
+            ep = Episode.new(
+              id: next_id,
+              agent_id: agent_id,
+              session_id: session_id,
+              ts: Time.now.to_i,
+              type: type,
+              content: content,
+              outcome: outcome,
+              importance: importance
+            )
+            @episodes << ep
+            ep
+          end
+        end
+
+        # @see Store#episodes
+        def episodes(agent_id:, last: 50, type: nil)
+          @mutex.synchronize do
+            result = @episodes.select { |e| e.agent_id == agent_id }
+            result = result.select { |e| e.type == type } if type
+            result.last(last)
+          end
+        end
+
+        # @see Store#retrieve
+        def retrieve(agent_id:, query: nil, limit: 10, type: nil)
+          eps = episodes(agent_id: agent_id, last: 1000, type: type)
+          return eps.last(limit) unless query
+
+          q = query.to_s.downcase
+          eps.select { |e| e.content.to_s.downcase.include?(q) }.last(limit)
+        end
+
+        # @see Store#store_fact
+        def store_fact(agent_id:, key:, value:, confidence: 1.0) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            @facts[agent_id] ||= {}
+            fact = Fact.new(
+              id: next_id,
+              agent_id: agent_id,
+              key: key.to_s,
+              value: value,
+              confidence: confidence,
+              updated_at: Time.now.to_i
+            )
+            @facts[agent_id][key.to_s] = fact
+            fact
+          end
+        end
+
+        # @see Store#facts
+        def facts(agent_id:)
+          @mutex.synchronize { (@facts[agent_id] || {}).dup }
+        end
+
+        # @see Store#record_reflection
+        def record_reflection(agent_id:, summary:, system_patch: nil, applied: false) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            rec = ReflectionRecord.new(
+              id: next_id,
+              agent_id: agent_id,
+              ts: Time.now.to_i,
+              summary: summary,
+              system_patch: system_patch,
+              applied: applied
+            )
+            @reflections << rec
+            rec
+          end
+        end
+
+        # @see Store#reflections
+        def reflections(agent_id:, applied: nil)
+          @mutex.synchronize do
+            result = @reflections.select { |r| r.agent_id == agent_id }
+            applied.nil? ? result : result.select { |r| r.applied == applied }
+          end
+        end
+
+        # @see Store#apply_reflection
+        def apply_reflection(id:)
+          @mutex.synchronize do
+            rec = @reflections.find { |r| r.id == id }
+            return false unless rec
+
+            idx = @reflections.index(rec)
+            @reflections[idx] = ReflectionRecord.new(**rec.to_h.merge(applied: true))
+            true
+          end
+        end
+
+        # @see Store#clear
+        def clear(agent_id:)
+          @mutex.synchronize do
+            @episodes.reject! { |e| e.agent_id == agent_id }
+            @facts.delete(agent_id)
+            @reflections.reject! { |r| r.agent_id == agent_id }
+          end
+        end
+
+        private
+
+        def next_id
+          @seq += 1
+        end
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/stores/sqlite.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    module Stores
+      # SQLite-backed persistent Store implementation.
+      #
+      # Uses SQLite3 with FTS5 for fast full-text search on episode content.
+      # Igniter ships with the +sqlite3+ gem as a standard dependency.
+      # Raises +Igniter::Memory::ConfigurationError+ if the runtime environment
+      # is incomplete and the gem cannot be loaded.
+      #
+      # @example In-memory SQLite (for tests)
+      #   store = Igniter::Memory::Stores::SQLite.new(path: ":memory:")
+      #
+      # @example Persistent file
+      #   store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/agent_memory.db")
+      class SQLite < Store # rubocop:disable Metrics/ClassLength
+        # @param path [String] file path for the database, or ":memory:" for transient storage
+        def initialize(path:) # rubocop:disable Lint/MissingSuper
+          require "sqlite3"
+        rescue LoadError
+          raise ConfigurationError,
+                "`igniter` now ships with a required `sqlite3` dependency. " \
+                "If it is missing in this environment, run bundle install or reinstall the gem."
+        else
+          @mutex = Mutex.new
+          @db    = ::SQLite3::Database.new(path)
+          @db.results_as_hash = true
+          create_schema!
+        end
+
+        # @see Store#record
+        def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists
+          @mutex.synchronize do
+            @db.execute(
+              "INSERT INTO episodes (agent_id, session_id, ts, type, content, outcome, importance) " \
+              "VALUES (?, ?, ?, ?, ?, ?, ?)",
+              [agent_id, session_id, Time.now.to_i, type.to_s, content.to_s, outcome, importance.to_f]
+            )
+            row_to_episode(
+              @db.get_first_row("SELECT * FROM episodes WHERE id = last_insert_rowid()")
+            )
+          end
+        end
+
+        # @see Store#episodes
+        def episodes(agent_id:, last: 50, type: nil) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            rows = if type
+                     @db.execute(
+                       "SELECT * FROM episodes WHERE agent_id = ? AND type = ? ORDER BY ts ASC LIMIT ?",
+                       [agent_id, type.to_s, last]
+                     )
+                   else
+                     @db.execute(
+                       "SELECT * FROM episodes WHERE agent_id = ? ORDER BY ts ASC LIMIT ?",
+                       [agent_id, last]
+                     )
+                   end
+            rows.map { |r| row_to_episode(r) }
+          end
+        end
+
+        # @see Store#retrieve
+        def retrieve(agent_id:, query: nil, limit: 10, type: nil) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            if query
+              fts_retrieve(agent_id, query, limit, type)
+            else
+              rows = if type
+                       @db.execute(
+                         "SELECT * FROM episodes WHERE agent_id = ? AND type = ? ORDER BY ts ASC LIMIT ?",
+                         [agent_id, type.to_s, limit]
+                       )
+                     else
+                       @db.execute(
+                         "SELECT * FROM episodes WHERE agent_id = ? ORDER BY ts ASC LIMIT ?",
+                         [agent_id, limit]
+                       )
+                     end
+              rows.map { |r| row_to_episode(r) }
+            end
+          end
+        end
+
+        # @see Store#store_fact
+        def store_fact(agent_id:, key:, value:, confidence: 1.0) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            serialized = value.to_s
+            @db.execute(
+              "INSERT OR REPLACE INTO facts (agent_id, key, value, confidence, updated_at) " \
+              "VALUES (?, ?, ?, ?, ?)",
+              [agent_id, key.to_s, serialized, confidence.to_f, Time.now.to_i]
+            )
+            row_to_fact(
+              @db.get_first_row("SELECT * FROM facts WHERE agent_id = ? AND key = ?", [agent_id, key.to_s])
+            )
+          end
+        end
+
+        # @see Store#facts
+        def facts(agent_id:)
+          @mutex.synchronize do
+            rows = @db.execute("SELECT * FROM facts WHERE agent_id = ?", [agent_id])
+            rows.each_with_object({}) do |row, hash|
+              fact = row_to_fact(row)
+              hash[fact.key] = fact
+            end
+          end
+        end
+
+        # @see Store#record_reflection
+        def record_reflection(agent_id:, summary:, system_patch: nil, applied: false)
+          @mutex.synchronize do
+            @db.execute(
+              "INSERT INTO reflections (agent_id, ts, summary, system_patch, applied) " \
+              "VALUES (?, ?, ?, ?, ?)",
+              [agent_id, Time.now.to_i, summary, system_patch, applied ? 1 : 0]
+            )
+            row_to_reflection(
+              @db.get_first_row("SELECT * FROM reflections WHERE id = last_insert_rowid()")
+            )
+          end
+        end
+
+        # @see Store#reflections
+        def reflections(agent_id:, applied: nil) # rubocop:disable Metrics/MethodLength
+          @mutex.synchronize do
+            rows = if applied.nil?
+                     @db.execute("SELECT * FROM reflections WHERE agent_id = ? ORDER BY ts ASC", [agent_id])
+                   else
+                     @db.execute(
+                       "SELECT * FROM reflections WHERE agent_id = ? AND applied = ? ORDER BY ts ASC",
+                       [agent_id, applied ? 1 : 0]
+                     )
+                   end
+            rows.map { |r| row_to_reflection(r) }
+          end
+        end
+
+        # @see Store#apply_reflection
+        def apply_reflection(id:)
+          @mutex.synchronize do
+            changes_before = @db.changes
+            @db.execute("UPDATE reflections SET applied = 1 WHERE id = ?", [id])
+            @db.changes > changes_before || @db.changes == 1
+          end
+        end
+
+        # @see Store#clear
+        def clear(agent_id:)
+          @mutex.synchronize do
+            @db.execute("DELETE FROM episodes WHERE agent_id = ?", [agent_id])
+            @db.execute("DELETE FROM facts WHERE agent_id = ?", [agent_id])
+            @db.execute("DELETE FROM reflections WHERE agent_id = ?", [agent_id])
+          end
+        end
+
+        private
+
+        def fts_retrieve(agent_id, query, limit, type) # rubocop:disable Metrics/MethodLength
+          rows = if type
+                   @db.execute(
+                     "SELECT e.* FROM episodes e " \
+                     "JOIN episodes_fts fts ON fts.rowid = e.id " \
+                     "WHERE fts.content MATCH ? AND e.agent_id = ? AND e.type = ? " \
+                     "ORDER BY e.ts ASC LIMIT ?",
+                     [query.to_s, agent_id, type.to_s, limit]
+                   )
+                 else
+                   @db.execute(
+                     "SELECT e.* FROM episodes e " \
+                     "JOIN episodes_fts fts ON fts.rowid = e.id " \
+                     "WHERE fts.content MATCH ? AND e.agent_id = ? " \
+                     "ORDER BY e.ts ASC LIMIT ?",
+                     [query.to_s, agent_id, limit]
+                   )
+                 end
+          rows.map { |r| row_to_episode(r) }
+        rescue ::SQLite3::Exception
+          # FTS5 match error (e.g. invalid query syntax) — fall back to LIKE
+          fallback_retrieve(agent_id, query, limit, type)
+        end
+
+        def fallback_retrieve(agent_id, query, limit, type) # rubocop:disable Metrics/MethodLength
+          q = "%#{query}%"
+          rows = if type
+                   @db.execute(
+                     "SELECT * FROM episodes WHERE agent_id = ? AND type = ? AND content LIKE ? " \
+                     "ORDER BY ts ASC LIMIT ?",
+                     [agent_id, type.to_s, q, limit]
+                   )
+                 else
+                   @db.execute(
+                     "SELECT * FROM episodes WHERE agent_id = ? AND content LIKE ? " \
+                     "ORDER BY ts ASC LIMIT ?",
+                     [agent_id, q, limit]
+                   )
+                 end
+          rows.map { |r| row_to_episode(r) }
+        end
+
+        def row_to_episode(row) # rubocop:disable Metrics/MethodLength
+          return nil unless row
+
+          Episode.new(
+            id: row["id"],
+            agent_id: row["agent_id"],
+            session_id: row["session_id"],
+            ts: row["ts"],
+            type: row["type"],
+            content: row["content"],
+            outcome: row["outcome"],
+            importance: row["importance"]
+          )
+        end
+
+        def row_to_fact(row)
+          return nil unless row
+
+          Fact.new(
+            id: row["id"],
+            agent_id: row["agent_id"],
+            key: row["key"],
+            value: row["value"],
+            confidence: row["confidence"],
+            updated_at: row["updated_at"]
+          )
+        end
+
+        def row_to_reflection(row)
+          return nil unless row
+
+          ReflectionRecord.new(
+            id: row["id"],
+            agent_id: row["agent_id"],
+            ts: row["ts"],
+            summary: row["summary"],
+            system_patch: row["system_patch"],
+            applied: row["applied"] == 1
+          )
+        end
+
+        def create_schema! # rubocop:disable Metrics/MethodLength
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS episodes (
+              id         INTEGER PRIMARY KEY AUTOINCREMENT,
+              agent_id   TEXT NOT NULL,
+              session_id TEXT,
+              ts         INTEGER NOT NULL,
+              type       TEXT NOT NULL,
+              content    TEXT NOT NULL,
+              outcome    TEXT,
+              importance REAL NOT NULL DEFAULT 0.5
+            );
+            CREATE INDEX IF NOT EXISTS idx_ep_agent ON episodes(agent_id, ts);
+            CREATE VIRTUAL TABLE IF NOT EXISTS episodes_fts USING fts5(
+              content, content='episodes', content_rowid='id'
+            );
+            CREATE TRIGGER IF NOT EXISTS ep_ai AFTER INSERT ON episodes BEGIN
+              INSERT INTO episodes_fts(rowid, content) VALUES (new.id, new.content);
+            END;
+            CREATE TABLE IF NOT EXISTS facts (
+              id         INTEGER PRIMARY KEY AUTOINCREMENT,
+              agent_id   TEXT NOT NULL,
+              key        TEXT NOT NULL,
+              value      TEXT,
+              confidence REAL DEFAULT 1.0,
+              updated_at INTEGER,
+              UNIQUE(agent_id, key)
+            );
+            CREATE TABLE IF NOT EXISTS reflections (
+              id           INTEGER PRIMARY KEY AUTOINCREMENT,
+              agent_id     TEXT NOT NULL,
+              ts           INTEGER NOT NULL,
+              summary      TEXT,
+              system_patch TEXT,
+              applied      INTEGER DEFAULT 0
+            );
+          SQL
+        end
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "memory/episode"
+require_relative "memory/fact"
+require_relative "memory/reflection_record"
+require_relative "memory/store"
+require_relative "memory/stores/in_memory"
+require_relative "memory/stores/sqlite"
+require_relative "memory/reflection_cycle"
+require_relative "memory/agent_memory"
+require_relative "memory/memorable"
+
+module Igniter
+  # Pluggable episodic memory system for Agents and Skills.
+  #
+  # Agents and Skills can record what happened (episodes), store learned facts,
+  # and trigger reflection cycles that analyse past behaviour.
+  #
+  # == Quick start
+  #
+  #   require "igniter/core/memory"
+  #
+  #   class MyAgent < Igniter::Agent
+  #     include Igniter::Memory::Memorable
+  #     enable_memory  # uses the global default InMemory store
+  #   end
+  #
+  # == Custom store
+  #
+  #   Igniter::Memory.default_store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/mem.db")
+  #
+  #   class MyAgent < Igniter::Agent
+  #     include Igniter::Memory::Memorable
+  #     enable_memory store: Igniter::Memory.default_store
+  #   end
+  #
+  # == Global configuration
+  #
+  #   Igniter::Memory.configure do |m|
+  #     m.default_store = Igniter::Memory::Stores::SQLite.new(path: "/var/app/memory.db")
+  #   end
+  module Memory
+    # Raised when a required dependency (e.g. sqlite3 gem) is missing or when
+    # Memory is misconfigured.
+    ConfigurationError = Class.new(Igniter::Error)
+
+    class << self
+      # Returns the global default store, creating an InMemory store on first access.
+      #
+      # @return [Store]
+      def default_store
+        @default_store ||= Stores::InMemory.new
+      end
+
+      # Override the global default store.
+      #
+      # @param store [Store]
+      # @return [Store]
+      attr_writer :default_store
+
+      # Yield self for block-style configuration.
+      #
+      # @example
+      #   Igniter::Memory.configure do |m|
+      #     m.default_store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/mem.db")
+      #   end
+      def configure
+        yield self
+      end
+
+      # Reset module-level state (primarily useful in tests).
+      #
+      # @return [void]
+      def reset!
+        @default_store = nil
+      end
+    end
+  end
+end