llmemory 0.2.1 → 0.2.3

data/lib/llmemory/long_term/procedural/skill.rb

@@ -17,10 +17,11 @@ module Llmemory
         DEFAULT_KIND = "prompt"
 
         attr_reader :id, :user_id, :name, :description, :body, :kind, :version,
-                    :success_count, :failure_count, :created_at, :updated_at
+                    :success_count, :failure_count, :provenance, :created_at, :updated_at
 
         def initialize(id:, user_id:, name:, body:, description: nil, kind: DEFAULT_KIND,
-                       version: 1, success_count: 0, failure_count: 0, created_at: nil, updated_at: nil)
+                       version: 1, success_count: 0, failure_count: 0, provenance: nil,
+                       created_at: nil, updated_at: nil)
           @id = id
           @user_id = user_id
           @name = name.to_s
@@ -30,6 +31,7 @@ module Llmemory
           @version = version.to_i
           @success_count = success_count.to_i
           @failure_count = failure_count.to_i
+          @provenance = provenance
           @created_at = created_at || Time.now
           @updated_at = updated_at || @created_at
         end
@@ -60,6 +62,7 @@ module Llmemory
             version: hash[:version] || hash["version"] || 1,
             success_count: hash[:success_count] || hash["success_count"] || 0,
             failure_count: hash[:failure_count] || hash["failure_count"] || 0,
+            provenance: hash[:provenance] || hash["provenance"],
             created_at: parse_time(hash[:created_at] || hash["created_at"]),
             updated_at: parse_time(hash[:updated_at] || hash["updated_at"])
           )
@@ -83,6 +86,7 @@ module Llmemory
             version: version,
             success_count: success_count,
             failure_count: failure_count,
+            provenance: provenance,
             created_at: created_at.respond_to?(:iso8601) ? created_at.iso8601(6) : created_at,
             updated_at: updated_at.respond_to?(:iso8601) ? updated_at.iso8601(6) : updated_at
           }

data/lib/llmemory/long_term/procedural/storage.rb

@@ -12,17 +12,24 @@ module Llmemory
       Storage = Storages::MemoryStorage
 
       module Storages
-        def self.build(store: nil, base_path: nil, database_url: nil)
+        def self.build(store: nil, base_path: nil, database_url: nil, cipher: nil)
+          resolved_cipher = cipher || Llmemory.build_cipher
           case (store || Llmemory.configuration.long_term_store).to_s.to_sym
           when :memory
             MemoryStorage.new
           when :file
-            FileStorage.new(base_path: base_path || Llmemory.configuration.long_term_storage_path)
+            FileStorage.new(
+              base_path: base_path || Llmemory.configuration.long_term_storage_path,
+              cipher: resolved_cipher
+            )
           when :postgres, :database
-            DatabaseStorage.new(database_url: database_url || Llmemory.configuration.database_url)
+            DatabaseStorage.new(
+              database_url: database_url || Llmemory.configuration.database_url,
+              cipher: resolved_cipher
+            )
           when :active_record, :activerecord
             require_relative "storages/active_record_storage"
-            ActiveRecordStorage.new
+            ActiveRecordStorage.new(cipher: resolved_cipher)
           else
             MemoryStorage.new
           end

data/lib/llmemory/long_term/procedural/storages/active_record_storage.rb

@@ -4,6 +4,7 @@ require "json"
 require "securerandom"
 require "time"
 require_relative "base"
+require_relative "../../../crypto/field_helpers"
 
 module Llmemory
   module LongTerm
@@ -13,7 +14,10 @@ module Llmemory
         # auto-deserializes jsonb to a Hash (string keys), which Skill.from_h
         # handles. Mirrors the file-based ActiveRecordStorage pattern.
         class ActiveRecordStorage < Base
-          def initialize
+          include Llmemory::Crypto::FieldHelpers
+
+          def initialize(cipher: nil)
+            @cipher = cipher || Llmemory.build_cipher
             self.class.load_models!
           end
 
@@ -30,53 +34,71 @@ module Llmemory
             data["created_at"] ||= Time.now.utc.iso8601
             rec = LlmemorySkill.find_or_initialize_by(id: id)
             rec.user_id = user_id
-            rec.data = data
-            rec.search_text = searchable_text(data)
+            rec.data = cipher.enabled? ? enc_json(data) : data
+            rec.search_text = enc(searchable_text(data))
             rec.created_at ||= Time.current
             rec.save!
             id
           end
 
           def get_skill(user_id, id)
-            LlmemorySkill.find_by(user_id: user_id, id: id)&.data
+            rec = LlmemorySkill.find_by(user_id: user_id, id: id)
+            return nil unless rec
+
+            decode_data(rec.data)
           end
 
-          def list_skills(user_id, limit: nil)
-            scope = LlmemorySkill.where(user_id: user_id).order(created_at: :desc)
+          def list_skills(user_id, limit: nil, offset: nil)
+            scope = LlmemorySkill.where(user_id: user_id, archived_at: nil).order(created_at: :desc)
             scope = scope.limit(limit) if limit && limit.to_i.positive?
-            scope.map(&:data)
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
+            scope.map { |r| decode_data(r.data) }
           end
 
           def search_skills(user_id, query)
-            token_scope(LlmemorySkill.where(user_id: user_id), "search_text", query)
-              .order(created_at: :desc).map(&:data)
+            token_scope(LlmemorySkill.where(user_id: user_id, archived_at: nil), "search_text", query)
+              .order(created_at: :desc).map { |r| decode_data(r.data) }
           end
 
           def find_skills_by_name(user_id, name)
-            LlmemorySkill.where(user_id: user_id).where("data->>'name' = ?", name.to_s).map(&:data)
+            if cipher.enabled?
+              LlmemorySkill.where(user_id: user_id, archived_at: nil).map { |r| decode_data(r.data) }
+                .select { |s| (s[:name] || s["name"]).to_s == name.to_s }
+            else
+              LlmemorySkill.where(user_id: user_id, archived_at: nil).where("data->>'name' = ?", name.to_s).map(&:data)
+            end
           end
 
           def record_outcome(user_id, skill_id, success:)
             rec = LlmemorySkill.find_by(user_id: user_id, id: skill_id)
             return nil unless rec
-            data = rec.data || {}
-            key = success ? "success_count" : "failure_count"
+            data = decode_data(rec.data) || {}
+            key = success ? :success_count : :failure_count
             data[key] = (data[key] || 0).to_i + 1
-            data["updated_at"] = Time.now.utc.iso8601
-            rec.data = data
-            rec.search_text = searchable_text(data)
+            data[:updated_at] = Time.now.utc.iso8601
+            rec.data = cipher.enabled? ? enc_json(data) : data
+            rec.search_text = enc(searchable_text(data))
             rec.save!
             data
           end
 
           def count_skills(user_id)
-            LlmemorySkill.where(user_id: user_id).count
+            LlmemorySkill.where(user_id: user_id, archived_at: nil).count
           end
 
           def delete_skills(user_id, ids)
             LlmemorySkill.where(user_id: user_id, id: Array(ids).map(&:to_s)).delete_all
           end
 
+          def archive_skills(user_id, ids)
+            LlmemorySkill.where(user_id: user_id, id: Array(ids).map(&:to_s), archived_at: nil)
+              .update_all(archived_at: Time.current)
+          end
+
+          def expired_skill_ids(user_id, cutoff:)
+            LlmemorySkill.where(user_id: user_id, archived_at: nil).where("created_at < ?", cutoff).pluck(:id)
+          end
+
           def list_users
             LlmemorySkill.distinct.pluck(:user_id)
           end
@@ -95,7 +117,15 @@ module Llmemory
           end
 
           def searchable_text(data)
-            [data["name"], data["description"], data["body"]].compact.join("\n")
+            h = data.is_a?(Hash) ? data : {}
+            [h["name"] || h[:name], h["description"] || h[:description], h["body"] || h[:body]].compact.join("\n")
+          end
+
+          def decode_data(raw)
+            return raw.transform_keys(&:to_sym) if raw.is_a?(Hash)
+            return dec_json(raw) if raw.is_a?(String) && cipher.encrypted?(raw)
+
+            raw
           end
         end
       end

data/lib/llmemory/long_term/procedural/storages/base.rb

@@ -16,7 +16,7 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#get_skill must be implemented"
           end
 
-          def list_skills(user_id, limit: nil)
+          def list_skills(user_id, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_skills must be implemented"
           end
 
@@ -43,6 +43,19 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#delete_skills must be implemented"
           end
 
+          # Soft-archives skills by id. Archived skills are excluded from
+          # list_skills / search_skills / count_skills but remain accessible via
+          # get_skill. Returns the number archived.
+          def archive_skills(user_id, ids)
+            raise NotImplementedError, "#{self.class}#archive_skills must be implemented"
+          end
+
+          # Returns skills whose created_at is older than the cutoff and that are
+          # not already archived. Used by the TTL maintenance job.
+          def expired_skill_ids(user_id, cutoff:)
+            raise NotImplementedError, "#{self.class}#expired_skill_ids must be implemented"
+          end
+
           def list_users
             raise NotImplementedError, "#{self.class}#list_users must be implemented"
           end

data/lib/llmemory/long_term/procedural/storages/database_storage.rb

@@ -4,6 +4,7 @@ require "json"
 require "securerandom"
 require "time"
 require_relative "base"
+require_relative "../../../crypto/field_helpers"
 
 module Llmemory
   module LongTerm
@@ -13,9 +14,12 @@ module Llmemory
         # (plus id/user_id/created_at and a denormalized search_text), mirroring
         # the file-based DatabaseStorage pattern.
         class DatabaseStorage < Base
-          def initialize(database_url: nil)
+          include Llmemory::Crypto::FieldHelpers
+
+          def initialize(database_url: nil, cipher: nil)
             @database_url = database_url || Llmemory.configuration.database_url
             @connection = nil
+            @cipher = cipher || Llmemory.build_cipher
           end
 
           def save_skill(user_id, skill)
@@ -27,7 +31,7 @@ module Llmemory
               "INSERT INTO llmemory_skills (id, user_id, data, search_text, created_at) " \
               "VALUES ($1, $2, $3::jsonb, $4, $5) " \
               "ON CONFLICT (id) DO UPDATE SET data = $3::jsonb, search_text = $4",
-              [id, user_id, JSON.generate(data), searchable_text(data), created_at_value(data)]
+              [id, user_id, store_data(data), enc(searchable_text(data)), created_at_value(data)]
             )
             id
           end
@@ -38,10 +42,11 @@ module Llmemory
             rows.any? ? parse_data(rows.first["data"]) : nil
           end
 
-          def list_skills(user_id, limit: nil)
+          def list_skills(user_id, limit: nil, offset: nil)
             ensure_tables!
-            sql = "SELECT data FROM llmemory_skills WHERE user_id = $1 ORDER BY created_at DESC"
+            sql = "SELECT data FROM llmemory_skills WHERE user_id = $1 AND archived_at IS NULL ORDER BY created_at DESC"
             sql += " LIMIT #{limit.to_i}" if limit && limit.to_i.positive?
+            sql += " OFFSET #{offset.to_i}" if offset && offset.to_i.positive?
             conn.exec_params(sql, [user_id]).map { |r| parse_data(r["data"]) }
           end
 
@@ -49,7 +54,7 @@ module Llmemory
             ensure_tables!
             suffix, params = token_filter("search_text", query, 2)
             conn.exec_params(
-              "SELECT data FROM llmemory_skills WHERE user_id = $1#{suffix} ORDER BY created_at DESC",
+              "SELECT data FROM llmemory_skills WHERE user_id = $1 AND archived_at IS NULL#{suffix} ORDER BY created_at DESC",
               [user_id, *params]
             ).map { |r| parse_data(r["data"]) }
           end
@@ -57,7 +62,7 @@ module Llmemory
           def find_skills_by_name(user_id, name)
             ensure_tables!
             conn.exec_params(
-              "SELECT data FROM llmemory_skills WHERE user_id = $1 AND data->>'name' = $2",
+              "SELECT data FROM llmemory_skills WHERE user_id = $1 AND archived_at IS NULL AND data->>'name' = $2",
               [user_id, name.to_s]
             ).map { |r| parse_data(r["data"]) }
           end
@@ -71,14 +76,14 @@ module Llmemory
             data[:updated_at] = Time.now.utc.iso8601
             conn.exec_params(
               "UPDATE llmemory_skills SET data = $3::jsonb, search_text = $4 WHERE user_id = $1 AND id = $2",
-              [user_id, skill_id, JSON.generate(data), searchable_text(data)]
+              [user_id, skill_id, store_data(data), enc(searchable_text(data))]
             )
             data
           end
 
           def count_skills(user_id)
             ensure_tables!
-            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_skills WHERE user_id = $1", [user_id]).first["c"].to_i
+            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_skills WHERE user_id = $1 AND archived_at IS NULL", [user_id]).first["c"].to_i
           end
 
           def delete_skills(user_id, ids)
@@ -88,6 +93,24 @@ module Llmemory
             end
           end
 
+          def archive_skills(user_id, ids)
+            ensure_tables!
+            Array(ids).sum do |id|
+              conn.exec_params(
+                "UPDATE llmemory_skills SET archived_at = NOW() WHERE user_id = $1 AND id = $2 AND archived_at IS NULL",
+                [user_id, id]
+              ).cmd_tuples
+            end
+          end
+
+          def expired_skill_ids(user_id, cutoff:)
+            ensure_tables!
+            conn.exec_params(
+              "SELECT id FROM llmemory_skills WHERE user_id = $1 AND archived_at IS NULL AND created_at < $2",
+              [user_id, cutoff.iso8601]
+            ).map { |r| r["id"] }
+          end
+
           def list_users
             ensure_tables!
             conn.exec("SELECT DISTINCT user_id FROM llmemory_skills").map { |r| r["user_id"] }
@@ -109,9 +132,11 @@ module Llmemory
                 user_id TEXT NOT NULL,
                 data JSONB NOT NULL DEFAULT '{}'::jsonb,
                 search_text TEXT,
-                created_at TIMESTAMPTZ NOT NULL
+                created_at TIMESTAMPTZ NOT NULL,
+                archived_at TIMESTAMPTZ
               );
               CREATE INDEX IF NOT EXISTS idx_llmemory_skills_user_id ON llmemory_skills(user_id);
+              ALTER TABLE llmemory_skills ADD COLUMN IF NOT EXISTS archived_at TIMESTAMPTZ;
             SQL
           end
 
@@ -123,11 +148,28 @@ module Llmemory
           end
 
           def parse_data(value)
-            JSON.parse(value.to_s, symbolize_names: true)
+            if value.is_a?(Hash)
+              return value.transform_keys(&:to_sym)
+            end
+
+            str = value.to_s
+            if cipher.encrypted?(str)
+              cipher.decrypt_json(str)
+            else
+              JSON.parse(str, symbolize_names: true)
+            end
           rescue JSON::ParserError
             {}
           end
 
+          def store_data(data)
+            if cipher.enabled?
+              JSON.generate(enc_json(data))
+            else
+              JSON.generate(data)
+            end
+          end
+
           def symbolize(hash)
             hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
           end

data/lib/llmemory/long_term/procedural/storages/file_storage.rb

@@ -4,22 +4,26 @@ require "fileutils"
 require "json"
 require "time"
 require_relative "base"
+require_relative "../../../crypto/field_helpers"
 
 module Llmemory
   module LongTerm
     module Procedural
       module Storages
         class FileStorage < Base
-          def initialize(base_path: nil)
+          include Llmemory::Crypto::FieldHelpers
+
+          def initialize(base_path: nil, cipher: nil)
             @base_path = base_path || Llmemory.configuration.long_term_storage_path || "./llmemory_data"
             @base_path = File.expand_path(@base_path)
+            @cipher = cipher || Llmemory.build_cipher
           end
 
           def save_skill(user_id, skill)
             id = skill[:id] || skill["id"] || "skill_#{next_seq(user_id)}"
             data = stringify_for_json(skill).merge("id" => id, "user_id" => user_id)
             data["created_at"] ||= Time.now.iso8601(6)
-            File.write(skill_path(user_id, id), JSON.generate(data))
+            write_skill_file(skill_path(user_id, id), data)
             id
           end
 
@@ -29,18 +33,19 @@ module Llmemory
             load_skill(path)
           end
 
-          def list_skills(user_id, limit: nil)
-            sorted = all_skills(user_id).sort_by { |s| s[:created_at] }.reverse
+          def list_skills(user_id, limit: nil, offset: nil)
+            sorted = active_skills(user_id).sort_by { |s| s[:created_at] }.reverse
+            sorted = sorted.drop(offset.to_i) if offset && offset.to_i.positive?
             limit && limit.to_i.positive? ? sorted.first(limit.to_i) : sorted
           end
 
           def search_skills(user_id, query)
             return list_skills(user_id) if query.to_s.strip.empty?
-            all_skills(user_id).select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
+            active_skills(user_id).select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
           end
 
           def find_skills_by_name(user_id, name)
-            all_skills(user_id).select { |s| s[:name].to_s == name.to_s }
+            active_skills(user_id).select { |s| s[:name].to_s == name.to_s }
           end
 
           def record_outcome(user_id, skill_id, success:)
@@ -49,14 +54,12 @@ module Llmemory
             key = success ? :success_count : :failure_count
             skill[key] = (skill[key] || 0).to_i + 1
             skill[:updated_at] = Time.now.iso8601(6)
-            File.write(skill_path(user_id, skill_id), JSON.generate(stringify_for_json(skill)))
+            write_skill_file(skill_path(user_id, skill_id), stringify_for_json(skill))
             skill
           end
 
           def count_skills(user_id)
-            dir = user_path(user_id, "skills")
-            return 0 unless Dir.exist?(dir)
-            Dir.children(dir).count { |f| f.end_with?(".json") }
+            active_skills(user_id).size
           end
 
           def delete_skills(user_id, ids)
@@ -68,6 +71,24 @@ module Llmemory
             end
           end
 
+          def archive_skills(user_id, ids)
+            Array(ids).map(&:to_s).count do |id|
+              path = skill_path(user_id, id)
+              next false unless File.file?(path)
+              data = load_skill_raw(path)
+              next false if data["archived_at"]
+              data["archived_at"] = Time.now.iso8601
+              write_skill_file(path, data)
+              true
+            end
+          end
+
+          def expired_skill_ids(user_id, cutoff:)
+            active_skills(user_id)
+              .select { |s| (s[:created_at] || Time.now) < cutoff }
+              .map { |s| s[:id].to_s }
+          end
+
           def list_users
             return [] unless Dir.exist?(@base_path)
             Dir.children(@base_path).select { |d| Dir.exist?(File.join(@base_path, d, "skills")) }
@@ -75,6 +96,10 @@ module Llmemory
 
           private
 
+          def active_skills(user_id)
+            all_skills(user_id).reject { |s| s[:archived_at] }
+          end
+
           def all_skills(user_id)
             dir = user_path(user_id, "skills")
             return [] unless Dir.exist?(dir)
@@ -82,7 +107,9 @@ module Llmemory
           end
 
           def load_skill(path)
-            data = JSON.parse(File.read(path), symbolize_names: true)
+            data = load_skill_raw(path)
+            return nil unless data
+
             data[:created_at] = parse_time(data[:created_at])
             data[:updated_at] = parse_time(data[:updated_at]) if data[:updated_at]
             data
@@ -90,6 +117,17 @@ module Llmemory
             nil
           end
 
+          def load_skill_raw(path)
+            raw = File.read(path)
+            json = cipher.enabled? && cipher.encrypted?(raw) ? cipher.decrypt(raw) : raw
+            JSON.parse(json, symbolize_names: true)
+          end
+
+          def write_skill_file(path, data)
+            payload = JSON.generate(data)
+            File.write(path, cipher.enabled? ? cipher.encrypt(payload) : payload)
+          end
+
           def skill_text(skill)
             [skill[:name], skill[:description], skill[:body]].compact.join("\n")
           end

data/lib/llmemory/long_term/procedural/storages/memory_storage.rb

@@ -25,18 +25,19 @@ module Llmemory
             @skills[user_id].find { |s| s[:id] == id }
           end
 
-          def list_skills(user_id, limit: nil)
-            sorted = @skills[user_id].sort_by { |s| s[:created_at] }.reverse
+          def list_skills(user_id, limit: nil, offset: nil)
+            sorted = active_skills(user_id).sort_by { |s| as_time(s[:created_at]) }.reverse
+            sorted = sorted.drop(offset.to_i) if offset && offset.to_i.positive?
             limit && limit.to_i.positive? ? sorted.first(limit.to_i) : sorted
           end
 
           def search_skills(user_id, query)
             return list_skills(user_id) if query.to_s.strip.empty?
-            @skills[user_id].select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
+            active_skills(user_id).select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
           end
 
           def find_skills_by_name(user_id, name)
-            @skills[user_id].select { |s| s[:name].to_s == name.to_s }
+            active_skills(user_id).select { |s| s[:name].to_s == name.to_s }
           end
 
           def record_outcome(user_id, skill_id, success:)
@@ -49,7 +50,7 @@ module Llmemory
           end
 
           def count_skills(user_id)
-            @skills[user_id].size
+            active_skills(user_id).size
           end
 
           def delete_skills(user_id, ids)
@@ -59,12 +60,42 @@ module Llmemory
             before - @skills[user_id].size
           end
 
+          def archive_skills(user_id, ids)
+            ids = Array(ids).map(&:to_s)
+            count = 0
+            @skills[user_id].each do |s|
+              next unless ids.include?(s[:id].to_s)
+              next if s[:archived_at]
+              s[:archived_at] = Time.now
+              count += 1
+            end
+            count
+          end
+
+          def expired_skill_ids(user_id, cutoff:)
+            active_skills(user_id)
+              .select { |s| as_time(s[:created_at]) < cutoff }
+              .map { |s| s[:id].to_s }
+          end
+
           def list_users
             @skills.keys
           end
 
           private
 
+          def active_skills(user_id)
+            @skills[user_id].reject { |s| s[:archived_at] }
+          end
+
+          def as_time(value)
+            return Time.now if value.nil?
+            return value if value.is_a?(Time)
+            Time.parse(value.to_s)
+          rescue ArgumentError
+            Time.now
+          end
+
           def symbolize(hash)
             hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
           end

data/lib/llmemory/maintenance/cognitive_pass.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Maintenance
+    # The cognitive maintenance pass closes CoALA's learning loop in one
+    # scheduled step. Independently, the gem exposes consolidation (short-term ->
+    # semantic), reflection (episodic -> insights), skill mining (episodic ->
+    # procedural) and TTL expiry. This pass orchestrates them so an agent learns
+    # from its experience and keeps its memory healthy without the consumer
+    # wiring each step by hand.
+    #
+    # Designed to run as a maintenance task (cron / Rails Job), per user. Each
+    # step is isolated: a failure in one is captured in the returned report
+    # (`:errors`) and never aborts the others.
+    #
+    # Returns:
+    #   {
+    #     consolidated: true/false/nil,   # nil when no `memory:` was supplied
+    #     insights: [insight_id, ...],
+    #     mined: [proposal_or_skill_id, ...],
+    #     expired: { episodic: N, procedural: M },
+    #     errors: { reflect: "...", mine: "...", ... }   # only failed steps
+    #   }
+    class CognitivePass
+      def self.run!(user_id, **kwargs)
+        new(user_id, **kwargs).run!
+      end
+
+      def initialize(user_id, memory: nil, episodic: nil, procedural: nil, semantic: nil,
+                     llm: nil, reflect: true, mine_skills: nil, expire: true,
+                     reflection_window: 10, mining_window: Llmemory::SkillMining::Miner::DEFAULT_WINDOW)
+        @user_id = user_id
+        @memory = memory
+        @episodic = episodic
+        @procedural = procedural
+        @semantic = semantic
+        @llm = llm
+        @reflect = reflect
+        @mine_skills = mine_skills.nil? ? Llmemory.configuration.skill_mining_enabled : mine_skills
+        @expire = expire
+        @reflection_window = reflection_window
+        @mining_window = mining_window
+      end
+
+      def run!
+        report = { consolidated: nil, insights: [], mined: [], expired: { episodic: 0, procedural: 0 }, errors: {} }
+
+        step(report, :consolidate) { report[:consolidated] = consolidate } if @memory
+        step(report, :reflect)     { report[:insights] = reflect } if @reflect
+        step(report, :mine)        { report[:mined] = mine } if @mine_skills
+        step(report, :expire)      { report[:expired] = expire } if @expire
+
+        report
+      end
+
+      private
+
+      def step(report, name)
+        yield
+      rescue StandardError => e
+        report[:errors][name] = e.message
+      end
+
+      def consolidate
+        @memory.consolidate!
+      end
+
+      def reflect
+        Reflection::Reflector.new(episodic: episodic, semantic: semantic, llm: @llm)
+          .reflect(window: @reflection_window)
+      end
+
+      def mine
+        SkillMining::Miner.new(episodic: episodic, procedural: procedural, llm: @llm)
+          .mine(window: @mining_window, auto_register: true)
+      end
+
+      def expire
+        TTLExpiry.run!(@user_id, episodic: episodic, procedural: procedural)
+      end
+
+      def episodic
+        @episodic ||= @memory&.episodic || Llmemory::LongTerm::Episodic::Memory.new(user_id: @user_id)
+      end
+
+      def procedural
+        @procedural ||= @memory&.procedural || Llmemory::LongTerm::Procedural::Memory.new(user_id: @user_id)
+      end
+
+      def semantic
+        @semantic ||= build_semantic
+      end
+
+      def build_semantic
+        llm_opts = @llm ? { llm: @llm } : {}
+        case (Llmemory.configuration.long_term_type || :file_based).to_s.to_sym
+        when :graph_based
+          Llmemory::LongTerm::GraphBased::Memory.new(
+            user_id: @user_id, storage: Llmemory::LongTerm::GraphBased::Storages.build, **llm_opts
+          )
+        else
+          Llmemory::LongTerm::FileBased::Memory.new(
+            user_id: @user_id, storage: Llmemory::LongTerm::FileBased::Storages.build, **llm_opts
+          )
+        end
+      end
+    end
+  end
+end