llmemory 0.2.1 → 0.2.2

data/lib/llmemory/cli/commands/maintain.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      # Runs the cognitive maintenance pass for a user: reflect -> mine skills ->
+      # expire. Each step is isolated; failures are reported, not fatal.
+      class Maintain < Commands::Base
+        def option_parser(parser)
+          parser.on("--[no-]reflect", "Distill insights from recent episodes (default: on)") { |v| @reflect = v }
+          parser.on("--mine-skills", "Mine and register skills from episodes (default: config)") { @mine = true }
+          parser.on("--[no-]expire", "Soft-archive entries past their TTL (default: on)") { |v| @expire = v }
+          parser.on("--window N", Integer, "Episodes to reflect over (default 10)") { |v| @window = v }
+          parser.on("--store TYPE", "Storage type (memory|file|postgres|active_record)") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory maintain USER_ID [--[no-]reflect] [--mine-skills] [--[no-]expire] [--window N] [--store TYPE]"
+            exit 1
+          end
+
+          opts = {
+            episodic: Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id, storage: episodic_storage(@store_type)),
+            procedural: Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id, storage: procedural_storage(@store_type)),
+            semantic: build_semantic(user_id),
+            reflect: @reflect.nil? ? true : @reflect,
+            expire: @expire.nil? ? true : @expire
+          }
+          opts[:mine_skills] = @mine unless @mine.nil?
+          opts[:reflection_window] = @window if @window
+
+          report = Llmemory::Maintenance::CognitivePass.run!(user_id, **opts)
+          print_report(user_id, report)
+        end
+
+        private
+
+        def build_semantic(user_id)
+          if Llmemory.configuration.long_term_type.to_s == "graph_based"
+            Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id, storage: graph_based_storage(@store_type))
+          else
+            Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id, storage: file_based_storage(@store_type))
+          end
+        end
+
+        def print_report(user_id, report)
+          expired = report[:expired] || {}
+          puts "Cognitive pass for #{user_id}:"
+          puts "  insights:     #{Array(report[:insights]).size}"
+          puts "  skills mined: #{Array(report[:mined]).size}"
+          puts "  expired:      episodic=#{expired[:episodic] || 0} procedural=#{expired[:procedural] || 0}"
+          errors = report[:errors] || {}
+          errors.each { |step, msg| puts "  error (#{step}): #{msg}" }
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/mine_skills.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      # Mines reusable skills from a user's successful episodes. Human-in-the-loop
+      # by default: prints proposals and writes nothing unless --register is given.
+      class MineSkills < Commands::Base
+        def option_parser(parser)
+          parser.on("--window N", Integer, "Episodes to mine (default 20)") { |v| @window = v }
+          parser.on("--outcomes LIST", "Comma-separated outcome allowlist (e.g. success,recovered)") { |v| @outcomes = v.split(",").map(&:strip) }
+          parser.on("--register", "Register the proposals instead of only printing them") { @register = true }
+          parser.on("--store TYPE", "Storage type (memory|file|postgres|active_record)") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory mine-skills USER_ID [--window N] [--outcomes LIST] [--register] [--store TYPE]"
+            exit 1
+          end
+
+          episodic = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id, storage: episodic_storage(@store_type))
+          procedural = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id, storage: procedural_storage(@store_type))
+          result = Llmemory::SkillMining::Miner.new(episodic: episodic, procedural: procedural).mine(
+            window: @window || Llmemory::SkillMining::Miner::DEFAULT_WINDOW,
+            outcomes: @outcomes,
+            auto_register: @register
+          )
+
+          if result.empty?
+            puts "No skills could be mined for user #{user_id}."
+            return
+          end
+
+          if @register
+            puts "Registered #{result.size} mined skill(s): #{result.join(', ')}"
+          else
+            puts "#{result.size} skill proposal(s) for user #{user_id} (not registered):"
+            result.each do |p|
+              puts "  - #{p[:name]} (#{p[:kind]}, confidence: #{p[:confidence]}): #{p[:description] || p[:body]}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli.rb

@@ -9,6 +9,8 @@ require_relative "cli/commands/episodic"
 require_relative "cli/commands/procedural"
 require_relative "cli/commands/working"
 require_relative "cli/commands/forget_log"
+require_relative "cli/commands/mine_skills"
+require_relative "cli/commands/maintain"
 require_relative "cli/commands/stats"
 require_relative "cli/commands/search"
 require_relative "cli/commands/mcp"
@@ -55,6 +57,8 @@ module Llmemory
         "skills" => Cli::Commands::Procedural,
         "working" => Cli::Commands::Working,
         "forget_log" => Cli::Commands::ForgetLog,
+        "mine_skills" => Cli::Commands::MineSkills,
+        "maintain" => Cli::Commands::Maintain,
         "search" => Cli::Commands::Search,
         "stats" => Cli::Commands::Stats,
         "mcp" => Cli::Commands::Mcp
@@ -80,6 +84,8 @@ module Llmemory
           skills USER_ID           List registered skills (procedural memory)
           working USER_ID SESSION  Show working-memory slots for a session
           forget-log USER_ID       Show audit of forgotten entries
+          mine-skills USER_ID      Mine reusable skills from episodes (--register to save)
+          maintain USER_ID         Run the cognitive maintenance pass (reflect/mine/expire)
           search USER_ID "query"   Search in memory
           stats [USER_ID]          Show statistics
           mcp [serve]              Start MCP server for LLM agents

data/lib/llmemory/configuration.rb

@@ -45,7 +45,10 @@ module Llmemory
                   :embedding_cache_enabled,
                   :embedding_cache_max_entries,
                   :max_message_chars,
-                  :message_sanitizer_enabled
+                  :message_sanitizer_enabled,
+                  :ttl_episodic_days,
+                  :ttl_procedural_days,
+                  :skill_mining_enabled
 
     def initialize
       @llm_provider = :openai
@@ -59,6 +62,9 @@ module Llmemory
       @long_term_storage_path = ENV["LLMEMORY_STORAGE_PATH"] || "./llmemory_data"
       @episodic_vector_enabled = false
       @procedural_vector_enabled = false
+      @ttl_episodic_days = nil
+      @ttl_procedural_days = nil
+      @skill_mining_enabled = false
       @database_url = ENV["DATABASE_URL"]
       @vector_store = nil
       @time_decay_half_life_days = 30

data/lib/llmemory/instrumentation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Llmemory
+  # Lightweight instrumentation seam. When ActiveSupport::Notifications is
+  # available (Rails apps, opt-in elsewhere), events are published with the
+  # `.llmemory` suffix so subscribers can hook into LLM calls, retrieval,
+  # writes and forgets for metrics, traces or cost dashboards. When AS is not
+  # loaded, the block is yielded transparently and no event is emitted.
+  #
+  # Events (payload keys are best-effort; subscribers should treat them as
+  # optional):
+  #
+  #   llm_invoke.llmemory       provider:, model:, prompt_chars:, response_chars:
+  #   llm_embed.llmemory        provider:, model:, text_chars:, dimensions:
+  #   memory_write.llmemory     memory_type:, user_id:
+  #   memory_forget.llmemory    memory_type:, user_id:, count:
+  #   retrieve.llmemory         query_chars:, candidates:, results:
+  #   iterative_retrieve.llmemory  hops:, total_results:
+  #   reflect.llmemory          window:, insights:
+  #   mine_skills.llmemory      window:, auto_register:
+  module Instrumentation
+    module_function
+
+    def instrument(event, payload = {})
+      name = "#{event}.llmemory"
+      if defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument(name, payload) { yield if block_given? }
+      else
+        yield if block_given?
+      end
+    end
+  end
+end

data/lib/llmemory/llm/anthropic.rb

@@ -16,22 +16,26 @@ module Llmemory
       end
 
       def invoke(prompt)
-        response = connection.post("v1/messages") do |req|
-          req.body = {
-            model: @model,
-            max_tokens: 1024,
-            messages: [{ role: "user", content: prompt }]
-          }.to_json
-          req.headers["Content-Type"] = "application/json"
-          req.headers["x-api-key"] = @api_key
-          req.headers["anthropic-version"] = "2023-06-01"
+        result = nil
+        Llmemory::Instrumentation.instrument(:llm_invoke, provider: :anthropic, model: @model, prompt_chars: prompt.to_s.length) do
+          response = connection.post("v1/messages") do |req|
+            req.body = {
+              model: @model,
+              max_tokens: 1024,
+              messages: [{ role: "user", content: prompt }]
+            }.to_json
+            req.headers["Content-Type"] = "application/json"
+            req.headers["x-api-key"] = @api_key
+            req.headers["anthropic-version"] = "2023-06-01"
+          end
+
+          raise Llmemory::LLMError, "Anthropic API error: #{response.body}" unless response.success?
+
+          body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
+          content = body.dig("content", 0, "text")
+          result = content&.strip || ""
         end
-
-        raise Llmemory::LLMError, "Anthropic API error: #{response.body}" unless response.success?
-
-        body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
-        content = body.dig("content", 0, "text")
-        content&.strip || ""
+        result
       end
 
       private

data/lib/llmemory/llm/openai.rb

@@ -16,20 +16,24 @@ module Llmemory
       end
 
       def invoke(prompt)
-        response = connection.post("chat/completions") do |req|
-          req.body = {
-            model: @model,
-            messages: [{ role: "user", content: prompt }],
-            temperature: 0.3
-          }.to_json
-          req.headers["Content-Type"] = "application/json"
-          req.headers["Authorization"] = "Bearer #{@api_key}"
-        end
+        result = nil
+        Llmemory::Instrumentation.instrument(:llm_invoke, provider: :openai, model: @model, prompt_chars: prompt.to_s.length) do
+          response = connection.post("chat/completions") do |req|
+            req.body = {
+              model: @model,
+              messages: [{ role: "user", content: prompt }],
+              temperature: 0.3
+            }.to_json
+            req.headers["Content-Type"] = "application/json"
+            req.headers["Authorization"] = "Bearer #{@api_key}"
+          end
 
-        raise Llmemory::LLMError, "OpenAI API error: #{response.body}" unless response.success?
+          raise Llmemory::LLMError, "OpenAI API error: #{response.body}" unless response.success?
 
-        body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
-        body.dig("choices", 0, "message", "content")&.strip || ""
+          body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
+          result = body.dig("choices", 0, "message", "content")&.strip || ""
+        end
+        result
       end
 
       # Calls the model with response_format json_schema (Structured Outputs).

data/lib/llmemory/long_term/episodic/memory.rb

@@ -52,8 +52,8 @@ module Llmemory
           @storage.list_episodes(@user_id, limit: limit).map { |e| Episode.from_h(e) }
         end
 
-        def episodes(limit: nil)
-          @storage.list_episodes(@user_id, limit: limit).map { |e| Episode.from_h(e) }
+        def episodes(limit: nil, offset: nil)
+          @storage.list_episodes(@user_id, limit: limit, offset: offset).map { |e| Episode.from_h(e) }
         end
 
         def find_episode(id)
@@ -84,24 +84,37 @@ module Llmemory
         # --- MemoryModule uniform interface ---
 
         def write(steps:, summary: nil, outcome: nil, importance: 0.5, **_meta)
-          record_episode(steps: steps, summary: summary, outcome: outcome, importance: importance)
+          result = nil
+          Llmemory::Instrumentation.instrument(:memory_write, memory_type: "episodic", user_id: @user_id) do
+            result = record_episode(steps: steps, summary: summary, outcome: outcome, importance: importance)
+          end
+          result
         end
 
-        def list(user_id: nil, limit: nil)
-          episodes(limit: limit)
+        def list(user_id: nil, limit: nil, offset: nil)
+          episodes(limit: limit, offset: offset)
         end
 
         def stats(user_id: nil)
           { episodes: count }
         end
 
-        def forget(ids:, reason: nil)
+        def forget(ids:, reason: nil, mode: :soft)
           requested = Array(ids).map(&:to_s)
           existing = @storage.list_episodes(@user_id).map { |e| (e[:id] || e["id"]).to_s }
-          removed = requested & existing
-          @storage.delete_episodes(@user_id, removed)
-          forget_log.record(@user_id, memory_type: "episodic", ids: removed, reason: reason)
-          removed.size
+          targeted = requested & existing
+          count = case mode
+          when :hard then @storage.delete_episodes(@user_id, targeted).to_i
+          else @storage.archive_episodes(@user_id, targeted).to_i
+          end
+          forget_log.record(@user_id, memory_type: "episodic", ids: targeted, reason: reason)
+          Llmemory::Instrumentation.instrument(:memory_forget, memory_type: "episodic", user_id: @user_id, count: count, mode: mode)
+          count
+        end
+
+        # Storage accessor for the TTL maintenance job.
+        def expired_ids(cutoff:)
+          @storage.expired_episode_ids(@user_id, cutoff: cutoff)
         end
 
         private

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

@@ -42,25 +42,35 @@ module Llmemory
             rec&.data
           end
 
-          def list_episodes(user_id, limit: nil)
-            scope = LlmemoryEpisode.where(user_id: user_id).order(created_at: :desc)
+          def list_episodes(user_id, limit: nil, offset: nil)
+            scope = LlmemoryEpisode.where(user_id: user_id, archived_at: nil).order(created_at: :desc)
             scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map(&:data)
           end
 
           def search_episodes(user_id, query)
-            token_scope(LlmemoryEpisode.where(user_id: user_id), "search_text", query)
+            token_scope(LlmemoryEpisode.where(user_id: user_id, archived_at: nil), "search_text", query)
               .order(created_at: :desc).map(&:data)
           end
 
           def count_episodes(user_id)
-            LlmemoryEpisode.where(user_id: user_id).count
+            LlmemoryEpisode.where(user_id: user_id, archived_at: nil).count
           end
 
           def delete_episodes(user_id, ids)
             LlmemoryEpisode.where(user_id: user_id, id: Array(ids).map(&:to_s)).delete_all
           end
 
+          def archive_episodes(user_id, ids)
+            LlmemoryEpisode.where(user_id: user_id, id: Array(ids).map(&:to_s), archived_at: nil)
+              .update_all(archived_at: Time.current)
+          end
+
+          def expired_episode_ids(user_id, cutoff:)
+            LlmemoryEpisode.where(user_id: user_id, archived_at: nil).where("created_at < ?", cutoff).pluck(:id)
+          end
+
           def list_users
             LlmemoryEpisode.distinct.pluck(:user_id)
           end

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

@@ -16,8 +16,8 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#get_episode must be implemented"
           end
 
-          # Newest first. Optionally capped by limit.
-          def list_episodes(user_id, limit: nil)
+          # Newest first. Optionally paginated with offset/limit.
+          def list_episodes(user_id, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_episodes must be implemented"
           end
 
@@ -34,6 +34,19 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#delete_episodes must be implemented"
           end
 
+          # Soft-archives episodes by id (sets archived_at on the record). Archived
+          # episodes are excluded from list_episodes / search_episodes / count_episodes
+          # but remain accessible via get_episode. Returns the number archived.
+          def archive_episodes(user_id, ids)
+            raise NotImplementedError, "#{self.class}#archive_episodes must be implemented"
+          end
+
+          # Returns episodes whose created_at is older than the cutoff and that are
+          # not already archived. Used by the TTL maintenance job.
+          def expired_episode_ids(user_id, cutoff:)
+            raise NotImplementedError, "#{self.class}#expired_episode_ids must be implemented"
+          end
+
           def list_users
             raise NotImplementedError, "#{self.class}#list_users must be implemented"
           end

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

@@ -38,10 +38,11 @@ module Llmemory
             rows.any? ? parse_data(rows.first["data"]) : nil
           end
 
-          def list_episodes(user_id, limit: nil)
+          def list_episodes(user_id, limit: nil, offset: nil)
             ensure_tables!
-            sql = "SELECT data FROM llmemory_episodes WHERE user_id = $1 ORDER BY created_at DESC"
+            sql = "SELECT data FROM llmemory_episodes 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,14 +50,14 @@ module Llmemory
             ensure_tables!
             suffix, params = token_filter("search_text", query, 2)
             conn.exec_params(
-              "SELECT data FROM llmemory_episodes WHERE user_id = $1#{suffix} ORDER BY created_at DESC",
+              "SELECT data FROM llmemory_episodes 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
 
           def count_episodes(user_id)
             ensure_tables!
-            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_episodes WHERE user_id = $1", [user_id]).first["c"].to_i
+            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_episodes WHERE user_id = $1 AND archived_at IS NULL", [user_id]).first["c"].to_i
           end
 
           def delete_episodes(user_id, ids)
@@ -66,6 +67,24 @@ module Llmemory
             end
           end
 
+          def archive_episodes(user_id, ids)
+            ensure_tables!
+            Array(ids).sum do |id|
+              conn.exec_params(
+                "UPDATE llmemory_episodes 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_episode_ids(user_id, cutoff:)
+            ensure_tables!
+            conn.exec_params(
+              "SELECT id FROM llmemory_episodes 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_episodes").map { |r| r["user_id"] }
@@ -87,9 +106,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_episodes_user_id ON llmemory_episodes(user_id);
+              ALTER TABLE llmemory_episodes ADD COLUMN IF NOT EXISTS archived_at TIMESTAMPTZ;
             SQL
           end
 

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

@@ -29,20 +29,19 @@ module Llmemory
             load_episode(path)
           end
 
-          def list_episodes(user_id, limit: nil)
-            sorted = all_episodes(user_id).sort_by { |e| e[:created_at] }.reverse
+          def list_episodes(user_id, limit: nil, offset: nil)
+            sorted = active_episodes(user_id).sort_by { |e| e[: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_episodes(user_id, query)
             return list_episodes(user_id) if query.to_s.strip.empty?
-            all_episodes(user_id).select { |e| Llmemory::Tokenizer.matches?(episode_text(e), query) }
+            active_episodes(user_id).select { |e| Llmemory::Tokenizer.matches?(episode_text(e), query) }
           end
 
           def count_episodes(user_id)
-            dir = user_path(user_id, "episodes")
-            return 0 unless Dir.exist?(dir)
-            Dir.children(dir).count { |f| f.end_with?(".json") }
+            active_episodes(user_id).size
           end
 
           def delete_episodes(user_id, ids)
@@ -54,6 +53,24 @@ module Llmemory
             end
           end
 
+          def archive_episodes(user_id, ids)
+            Array(ids).map(&:to_s).count do |id|
+              path = episode_path(user_id, id)
+              next false unless File.file?(path)
+              data = JSON.parse(File.read(path))
+              next false if data["archived_at"]
+              data["archived_at"] = Time.now.iso8601
+              File.write(path, JSON.generate(data))
+              true
+            end
+          end
+
+          def expired_episode_ids(user_id, cutoff:)
+            active_episodes(user_id)
+              .select { |e| (e[:created_at] || Time.now) < cutoff }
+              .map { |e| e[: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, "episodes")) }
@@ -61,6 +78,10 @@ module Llmemory
 
           private
 
+          def active_episodes(user_id)
+            all_episodes(user_id).reject { |e| e[:archived_at] }
+          end
+
           def all_episodes(user_id)
             dir = user_path(user_id, "episodes")
             return [] unless Dir.exist?(dir)

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

@@ -25,18 +25,19 @@ module Llmemory
             @episodes[user_id].find { |e| e[:id] == id }
           end
 
-          def list_episodes(user_id, limit: nil)
-            sorted = @episodes[user_id].sort_by { |e| e[:created_at] }.reverse
+          def list_episodes(user_id, limit: nil, offset: nil)
+            sorted = active_episodes(user_id).sort_by { |e| as_time(e[: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_episodes(user_id, query)
             return list_episodes(user_id) if query.to_s.strip.empty?
-            @episodes[user_id].select { |e| Llmemory::Tokenizer.matches?(episode_text(e), query) }
+            active_episodes(user_id).select { |e| Llmemory::Tokenizer.matches?(episode_text(e), query) }
           end
 
           def count_episodes(user_id)
-            @episodes[user_id].size
+            active_episodes(user_id).size
           end
 
           def delete_episodes(user_id, ids)
@@ -46,12 +47,42 @@ module Llmemory
             before - @episodes[user_id].size
           end
 
+          def archive_episodes(user_id, ids)
+            ids = Array(ids).map(&:to_s)
+            count = 0
+            @episodes[user_id].each do |e|
+              next unless ids.include?(e[:id].to_s)
+              next if e[:archived_at]
+              e[:archived_at] = Time.now
+              count += 1
+            end
+            count
+          end
+
+          def expired_episode_ids(user_id, cutoff:)
+            active_episodes(user_id)
+              .select { |e| as_time(e[:created_at]) < cutoff }
+              .map { |e| e[:id].to_s }
+          end
+
           def list_users
             @episodes.keys
           end
 
           private
 
+          def active_episodes(user_id)
+            @episodes[user_id].reject { |e| e[: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/long_term/file_based/memory.rb

@@ -108,11 +108,15 @@ module Llmemory
         # --- MemoryModule uniform interface ---
 
         def write(payload, **_meta)
-          memorize(payload)
+          result = nil
+          Llmemory::Instrumentation.instrument(:memory_write, memory_type: "file_based", user_id: @user_id) do
+            result = memorize(payload)
+          end
+          result
         end
 
-        def list(user_id: nil, limit: nil)
-          @storage.list_items(user_id: user_id || @user_id, limit: limit)
+        def list(user_id: nil, limit: nil, offset: nil)
+          @storage.list_items(user_id: user_id || @user_id, limit: limit, offset: offset)
         end
 
         def stats(user_id: nil)
@@ -120,7 +124,10 @@ module Llmemory
         end
 
         # Removes items/resources by id and records the removal in the audit log.
-        def forget(ids:, reason: nil)
+        # Note: file-based storages currently implement `archive_*` as physical
+        # removal — `mode: :soft` and `mode: :hard` are functionally equivalent
+        # here. Kept for API uniformity.
+        def forget(ids:, reason: nil, mode: :soft)
           requested = Array(ids).map(&:to_s)
           existing = (@storage.get_all_items(@user_id) + @storage.get_all_resources(@user_id))
             .map { |r| (r[:id] || r["id"]).to_s }
@@ -128,6 +135,7 @@ module Llmemory
           @storage.archive_items(@user_id, removed)
           @storage.archive_resources(@user_id, removed)
           forget_log.record(@user_id, memory_type: "file_based", ids: removed, reason: reason)
+          Llmemory::Instrumentation.instrument(:memory_forget, memory_type: "file_based", user_id: @user_id, count: removed.size, mode: mode)
           removed.size
         end