llmemory 0.2.1 → 0.2.2

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

@@ -123,17 +123,19 @@ module Llmemory
              LlmemoryCategory.distinct.pluck(:user_id)).uniq
           end
 
-          def list_resources(user_id:, limit: nil)
+          def list_resources(user_id:, limit: nil, offset: nil)
             scope = LlmemoryResource.where(user_id: user_id).order(:created_at)
             scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map { |r| row_to_resource(r) }
           end
 
-          def list_items(user_id:, category: nil, limit: nil)
+          def list_items(user_id:, category: nil, limit: nil, offset: nil)
             scope = LlmemoryItem.where(user_id: user_id)
             scope = scope.where(category: category) if category
             scope = scope.order(:created_at)
             scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map { |r| row_to_item(r) }
           end
 

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

@@ -69,11 +69,11 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#list_users must be implemented"
           end
 
-          def list_resources(user_id:, limit: nil)
+          def list_resources(user_id:, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_resources must be implemented"
           end
 
-          def list_items(user_id:, category: nil, limit: nil)
+          def list_items(user_id:, category: nil, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_items must be implemented"
           end
 

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

@@ -169,15 +169,16 @@ module Llmemory
              conn.exec("SELECT DISTINCT user_id FROM llmemory_categories").map { |r| r["user_id"] }).uniq
           end
 
-          def list_resources(user_id:, limit: nil)
+          def list_resources(user_id:, limit: nil, offset: nil)
             ensure_tables!
             sql = "SELECT id, text, created_at FROM llmemory_resources WHERE user_id = $1 ORDER BY created_at"
             sql += " LIMIT #{limit.to_i}" if limit && limit.to_i.positive?
+            sql += " OFFSET #{offset.to_i}" if offset && offset.to_i.positive?
             rows = conn.exec_params(sql, [user_id])
             rows_to_resources(rows)
           end
 
-          def list_items(user_id:, category: nil, limit: nil)
+          def list_items(user_id:, category: nil, limit: nil, offset: nil)
             ensure_tables!
             sql = "SELECT id, category, content, source_resource_id, importance, provenance, created_at FROM llmemory_items WHERE user_id = $1"
             params = [user_id]
@@ -187,6 +188,7 @@ module Llmemory
             end
             sql += " ORDER BY created_at"
             sql += " LIMIT #{limit.to_i}" if limit && limit.to_i.positive?
+            sql += " OFFSET #{offset.to_i}" if offset && offset.to_i.positive?
             rows = params.size == 1 ? conn.exec_params(sql, params) : conn.exec_params(sql, params)
             rows_to_items(rows)
           end

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

@@ -152,14 +152,16 @@ module Llmemory
             Dir.children(@base_path).select { |e| File.directory?(File.join(@base_path, e)) && !e.start_with?(".") }
           end
 
-          def list_resources(user_id:, limit: nil)
+          def list_resources(user_id:, limit: nil, offset: nil)
             list = get_all_resources(user_id)
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             limit ? list.take(limit) : list
           end
 
-          def list_items(user_id:, category: nil, limit: nil)
+          def list_items(user_id:, category: nil, limit: nil, offset: nil)
             list = get_all_items(user_id)
             list = list.select { |i| (i[:category] || i["category"]).to_s == category.to_s } if category
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             list = list.take(limit) if limit
             list
           end

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

@@ -98,17 +98,19 @@ module Llmemory
             (@resources.keys + @items.keys + @categories.keys).uniq
           end
 
-          def list_resources(user_id:, limit: nil)
+          def list_resources(user_id:, limit: nil, offset: nil)
             list = @resources[user_id].dup
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             limit ? list.take(limit) : list
           end
 
-          def list_items(user_id:, category: nil, limit: nil)
+          def list_items(user_id:, category: nil, limit: nil, offset: nil)
             list = if category
               @items[user_id].select { |i| i[:category].to_s == category.to_s }
             else
               @items[user_id].dup
             end
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             list = list.take(limit) if limit
             list
           end

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

@@ -78,11 +78,15 @@ module Llmemory
         # --- MemoryModule uniform interface ---
 
         def write(payload, **_meta)
-          memorize(payload)
+          result = nil
+          Llmemory::Instrumentation.instrument(:memory_write, memory_type: "graph_based", user_id: @user_id) do
+            result = memorize(payload)
+          end
+          result
         end
 
-        def list(user_id: nil, limit: nil)
-          @graph_storage.list_nodes(user_id || @user_id, limit: limit)
+        def list(user_id: nil, limit: nil, offset: nil)
+          @graph_storage.list_nodes(user_id || @user_id, limit: limit, offset: offset)
         end
 
         def stats(user_id: nil)
@@ -95,9 +99,13 @@ module Llmemory
         # removal in the audit log. Edges are soft-archived (archived_at) so they
         # no longer appear in retrieval; nodes are left in place (a node may still
         # be referenced by other active edges). Returns the number archived.
-        def forget(ids:, reason: nil)
+        def forget(ids:, reason: nil, mode: :soft)
+          # `:hard` would physically delete edge rows; not yet wired (the graph
+          # store only exposes soft archive_edge). Both modes route to archive
+          # for now; behavior is the same — kept for API uniformity.
           archived = Array(ids).map(&:to_s).select { |edge_id| @kg.archive_edge(edge_id) }
           forget_log.record(@user_id, memory_type: "graph_based", ids: archived, reason: reason)
+          Llmemory::Instrumentation.instrument(:memory_forget, memory_type: "graph_based", user_id: @user_id, count: archived.size, mode: mode)
           archived.size
         end
 

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

@@ -52,10 +52,11 @@ module Llmemory
             record_to_node(rec) if rec
           end
 
-          def list_nodes(user_id, entity_type: nil, limit: nil)
+          def list_nodes(user_id, entity_type: nil, limit: nil, offset: nil)
             scope = LlmemoryGraphNode.where(user_id: user_id)
             scope = scope.where(entity_type: entity_type) if entity_type
             scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map { |r| record_to_node(r) }
           end
 
@@ -106,12 +107,13 @@ module Llmemory
             (LlmemoryGraphNode.distinct.pluck(:user_id) + LlmemoryGraphEdge.distinct.pluck(:user_id)).uniq
           end
 
-          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil)
+          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil, offset: nil)
             scope = LlmemoryGraphEdge.where(user_id: user_id, archived_at: nil)
             scope = scope.where(subject_id: subject_id) if subject_id
             scope = scope.where(predicate: predicate) if predicate
             scope = scope.order(created_at: :desc) if limit && limit.to_i.positive?
             scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map { |r| record_to_edge(r) }
           end
 

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

@@ -17,7 +17,7 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#find_node_by_name must be implemented"
           end
 
-          def list_nodes(user_id, entity_type: nil, limit: nil)
+          def list_nodes(user_id, entity_type: nil, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_nodes must be implemented"
           end
 
@@ -37,7 +37,7 @@ module Llmemory
             raise NotImplementedError, "#{self.class}#list_users must be implemented"
           end
 
-          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil)
+          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil, offset: nil)
             raise NotImplementedError, "#{self.class}#list_edges must be implemented"
           end
 

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

@@ -43,9 +43,10 @@ module Llmemory
             @nodes[user_id].values.find { |n| n.entity_type == entity_type.to_s && n.name.to_s == name.to_s }
           end
 
-          def list_nodes(user_id, entity_type: nil, limit: nil)
+          def list_nodes(user_id, entity_type: nil, limit: nil, offset: nil)
             list = @nodes[user_id].values
             list = list.select { |n| n.entity_type.to_s == entity_type.to_s } if entity_type
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             limit ? list.take(limit) : list
           end
 
@@ -106,8 +107,9 @@ module Llmemory
             (@nodes.keys + @edges.keys).uniq
           end
 
-          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil)
+          def list_edges(user_id, subject_id: nil, predicate: nil, limit: nil, offset: nil)
             list = find_edges(user_id, subject_id: subject_id, predicate: predicate, object_id: nil, include_archived: false)
+            list = list.drop(offset.to_i) if offset && offset.to_i.positive?
             limit ? list.take(limit) : list
           end
 

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

@@ -31,11 +31,11 @@ module Llmemory
 
         # Registers a skill. If `version` is omitted and a skill with the same
         # name exists, the version auto-increments (skill evolution).
-        def register_skill(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil)
+        def register_skill(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil, provenance: nil)
           version ||= next_version_for(name)
           skill = Skill.new(
             id: nil, user_id: @user_id, name: name, body: body,
-            description: description, kind: kind, version: version
+            description: description, kind: kind, version: version, provenance: provenance
           )
           id = @storage.save_skill(@user_id, skill.to_h)
           index_vector(id, skill.searchable_text)
@@ -52,8 +52,8 @@ module Llmemory
           raw && Skill.from_h(raw)
         end
 
-        def skills(limit: nil)
-          @storage.list_skills(@user_id, limit: limit).map { |s| Skill.from_h(s) }
+        def skills(limit: nil, offset: nil)
+          @storage.list_skills(@user_id, limit: limit, offset: offset).map { |s| Skill.from_h(s) }
         end
 
         def count
@@ -83,25 +83,38 @@ module Llmemory
 
         # --- MemoryModule uniform interface ---
 
-        def write(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil, **_meta)
-          register_skill(name: name, body: body, description: description, kind: kind, version: version)
+        def write(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil, provenance: nil, **_meta)
+          result = nil
+          Llmemory::Instrumentation.instrument(:memory_write, memory_type: "procedural", user_id: @user_id) do
+            result = register_skill(name: name, body: body, description: description, kind: kind, version: version, provenance: provenance)
+          end
+          result
         end
 
-        def list(user_id: nil, limit: nil)
-          skills(limit: limit)
+        def list(user_id: nil, limit: nil, offset: nil)
+          skills(limit: limit, offset: offset)
         end
 
         def stats(user_id: nil)
           { skills: count }
         end
 
-        def forget(ids:, reason: nil)
+        def forget(ids:, reason: nil, mode: :soft)
           requested = Array(ids).map(&:to_s)
           existing = @storage.list_skills(@user_id).map { |s| (s[:id] || s["id"]).to_s }
-          removed = requested & existing
-          @storage.delete_skills(@user_id, removed)
-          forget_log.record(@user_id, memory_type: "procedural", ids: removed, reason: reason)
-          removed.size
+          targeted = requested & existing
+          count = case mode
+          when :hard then @storage.delete_skills(@user_id, targeted).to_i
+          else @storage.archive_skills(@user_id, targeted).to_i
+          end
+          forget_log.record(@user_id, memory_type: "procedural", ids: targeted, reason: reason)
+          Llmemory::Instrumentation.instrument(:memory_forget, memory_type: "procedural", user_id: @user_id, count: count, mode: mode)
+          count
+        end
+
+        # Storage accessor for the TTL maintenance job.
+        def expired_ids(cutoff:)
+          @storage.expired_skill_ids(@user_id, cutoff: cutoff)
         end
 
         private

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/storages/active_record_storage.rb

@@ -41,19 +41,20 @@ module Llmemory
             LlmemorySkill.find_by(user_id: user_id, id: id)&.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 = scope.offset(offset) if offset && offset.to_i.positive?
             scope.map(&:data)
           end
 
           def search_skills(user_id, query)
-            token_scope(LlmemorySkill.where(user_id: user_id), "search_text", query)
+            token_scope(LlmemorySkill.where(user_id: user_id, archived_at: nil), "search_text", query)
               .order(created_at: :desc).map(&:data)
           end
 
           def find_skills_by_name(user_id, name)
-            LlmemorySkill.where(user_id: user_id).where("data->>'name' = ?", name.to_s).map(&:data)
+            LlmemorySkill.where(user_id: user_id, archived_at: nil).where("data->>'name' = ?", name.to_s).map(&:data)
           end
 
           def record_outcome(user_id, skill_id, success:)
@@ -70,13 +71,22 @@ module Llmemory
           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

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

@@ -38,10 +38,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 +50,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 +58,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
@@ -78,7 +79,7 @@ module Llmemory
 
           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 +89,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 +128,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
 

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

@@ -29,18 +29,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:)
@@ -54,9 +55,7 @@ module Llmemory
           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 +67,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 = 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_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 +92,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)

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