igniter 0.5.1 → 0.5.2

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

@@ -1,115 +0,0 @@
-# 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

@@ -1,136 +0,0 @@
-# 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

@@ -1,286 +0,0 @@
-# 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

@@ -1,80 +0,0 @@
-# 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