llmemory 0.2.1 → 0.2.2

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

data/lib/llmemory/maintenance/ttl_expiry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Maintenance
+    # TTL expiry job: soft-archives episodic/procedural entries whose age
+    # exceeds the configured per-type TTL. Designed to run as a maintenance
+    # task (cron / Rails Job). Idempotent — already-archived entries are
+    # skipped by the storage layer.
+    #
+    # Reads `Llmemory.configuration.ttl_episodic_days` and
+    # `Llmemory.configuration.ttl_procedural_days`. A nil/zero TTL disables
+    # expiry for that memory type.
+    #
+    # Returns a hash `{ episodic: N, procedural: M }` with the number of
+    # entries archived per type for the given user.
+    class TTLExpiry
+      DEFAULT_REASON = "ttl_expired"
+
+      def self.run!(user_id, episodic: nil, procedural: nil, reason: DEFAULT_REASON)
+        new(user_id, episodic: episodic, procedural: procedural, reason: reason).run!
+      end
+
+      def initialize(user_id, episodic: nil, procedural: nil, reason: DEFAULT_REASON)
+        @user_id = user_id
+        @episodic = episodic
+        @procedural = procedural
+        @reason = reason
+      end
+
+      def run!
+        {
+          episodic: expire(memory: @episodic ||= Llmemory::LongTerm::Episodic::Memory.new(user_id: @user_id),
+                           ttl_days: Llmemory.configuration.ttl_episodic_days),
+          procedural: expire(memory: @procedural ||= Llmemory::LongTerm::Procedural::Memory.new(user_id: @user_id),
+                             ttl_days: Llmemory.configuration.ttl_procedural_days)
+        }
+      end
+
+      private
+
+      def expire(memory:, ttl_days:)
+        return 0 unless ttl_days && ttl_days.to_f.positive?
+        cutoff = Time.now - (ttl_days.to_f * 86400)
+        ids = memory.expired_ids(cutoff: cutoff)
+        return 0 if ids.empty?
+        memory.forget(ids: ids, reason: @reason, mode: :soft)
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "maintenance/runner"
+require_relative "maintenance/ttl_expiry"
+require_relative "maintenance/cognitive_pass"
 
 module Llmemory
   module Maintenance

data/lib/llmemory/mcp/server.rb

@@ -17,6 +17,8 @@ require_relative "tools/memory_skill_register"
 require_relative "tools/memory_skill_report"
 require_relative "tools/memory_skills"
 require_relative "tools/memory_forget"
+require_relative "tools/memory_mine_skills"
+require_relative "tools/memory_maintain"
 
 module Llmemory
   module MCP
@@ -169,7 +171,9 @@ module Llmemory
           Tools::MemorySkillRegister,
           Tools::MemorySkillReport,
           Tools::MemorySkills,
-          Tools::MemoryForget
+          Tools::MemoryForget,
+          Tools::MemoryMineSkills,
+          Tools::MemoryMaintain
         ]
       end
 

data/lib/llmemory/mcp/tools/memory_maintain.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryMaintain < ::MCP::Tool
+        description "Run the cognitive maintenance pass for a user: reflect (episodes -> insights), mine skills (episodes -> procedural), and expire entries past their TTL. Each step is isolated; a failure in one is reported and does not abort the others. Returns a summary report."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            reflect: { type: "boolean", description: "Distill insights from recent episodes (default true)" },
+            mine_skills: { type: "boolean", description: "Mine reusable skills from episodes and register them (default: config.skill_mining_enabled)" },
+            expire: { type: "boolean", description: "Soft-archive entries past their TTL (default true)" },
+            reflection_window: { type: "integer", description: "Episodes to reflect over (default 10)" },
+            mining_window: { type: "integer", description: "Episodes to mine for skills (default 20)" }
+          },
+          required: ["user_id"]
+        )
+
+        class << self
+          def call(user_id:, reflect: true, mine_skills: nil, expire: true,
+                   reflection_window: nil, mining_window: nil, server_context: nil)
+            opts = { reflect: reflect, expire: expire }
+            opts[:mine_skills] = mine_skills unless mine_skills.nil?
+            opts[:reflection_window] = reflection_window.to_i unless reflection_window.nil?
+            opts[:mining_window] = mining_window.to_i unless mining_window.nil?
+
+            report = Llmemory::Maintenance::CognitivePass.run!(user_id, **opts)
+            ::MCP::Tool::Response.new([{ type: "text", text: format_report(user_id, report) }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error running maintenance pass: #{e.message}" }], error: true)
+          end
+
+          private
+
+          def format_report(user_id, report)
+            expired = report[:expired] || {}
+            lines = [
+              "Cognitive pass for #{user_id}:",
+              "  insights: #{Array(report[:insights]).size}",
+              "  skills mined: #{Array(report[:mined]).size}",
+              "  expired: episodic=#{expired[:episodic] || 0} procedural=#{expired[:procedural] || 0}"
+            ]
+            errors = report[:errors] || {}
+            lines << "  errors: #{errors.map { |k, v| "#{k}: #{v}" }.join('; ')}" unless errors.empty?
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/mcp/tools/memory_mine_skills.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryMineSkills < ::MCP::Tool
+        description "Mine reusable skills from a user's successful episode trajectories (procedural learning). Human-in-the-loop by default: returns skill *proposals* and writes nothing. Set auto_register=true to register them in procedural memory (with provenance back to the source episodes)."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            window: { type: "integer", description: "Episodes to mine (default 20)" },
+            outcomes: { type: "array", items: { type: "string" }, description: "Optional allowlist of outcome labels to pre-filter episodes (e.g. ['success'])" },
+            auto_register: { type: "boolean", description: "Register the proposals instead of only returning them (default false)" }
+          },
+          required: ["user_id"]
+        )
+
+        class << self
+          def call(user_id:, window: nil, outcomes: nil, auto_register: false, server_context: nil)
+            episodic = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            procedural = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            result = Llmemory::SkillMining::Miner.new(episodic: episodic, procedural: procedural).mine(
+              window: (window || Llmemory::SkillMining::Miner::DEFAULT_WINDOW).to_i,
+              outcomes: outcomes,
+              auto_register: auto_register
+            )
+
+            ::MCP::Tool::Response.new([{ type: "text", text: format_result(user_id, result, auto_register) }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error mining skills: #{e.message}" }], error: true)
+          end
+
+          private
+
+          def format_result(user_id, result, auto_register)
+            return "No skills could be mined for user #{user_id}." if result.empty?
+
+            if auto_register
+              "Registered #{result.size} mined skill(s): #{result.join(', ')}"
+            else
+              lines = ["#{result.size} skill proposal(s) for user #{user_id} (not registered):"]
+              result.each do |p|
+                lines << "  - #{p[:name]} (#{p[:kind]}, confidence: #{p[:confidence]}): #{p[:description] || p[:body]}"
+              end
+              lines.join("\n")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/memory.rb

@@ -53,6 +53,26 @@ module Llmemory
       Actions::Reason.call(working_memory: working_memory, template: template, into: into, parse: parse, llm: @llm)
     end
 
+    # Mines recent episodes for reusable skills (Voyager-style). Human-in-the-loop
+    # by default: returns skill proposals and writes nothing. With
+    # `auto_register: true`, registers them in procedural memory (with provenance
+    # back to the source episodes) and returns the new skill ids.
+    def mine_skills!(window: SkillMining::Miner::DEFAULT_WINDOW, outcomes: nil, auto_register: false)
+      SkillMining::Miner.new(episodic: episodic, procedural: procedural, llm: @llm)
+        .mine(window: window, outcomes: outcomes, auto_register: auto_register)
+    end
+
+    # Cognitive maintenance pass: consolidate -> reflect -> mine skills -> expire,
+    # in one step, closing the CoALA learning loop. Each step is isolated; a
+    # failure in one is captured in the report and never aborts the others.
+    def maintain!(**opts)
+      Maintenance::CognitivePass.run!(
+        @user_id,
+        memory: self, episodic: episodic, procedural: procedural, semantic: @long_term, llm: @llm,
+        **opts
+      )
+    end
+
     def add_message(role:, content:)
       msgs = messages
       msgs << { role: role.to_sym, content: content.to_s }

data/lib/llmemory/memory_module.rb

@@ -6,10 +6,10 @@ module Llmemory
   # abstractions; this mixin gives any memory store the same agent-facing
   # surface so frameworks can treat them polymorphically:
   #
-  #   read(query, user_id:, limit:)  -> relevant entries (retrieval)
-  #   write(payload, ...)            -> ingest into the store (learning)
-  #   list(user_id:, limit:)         -> enumerate stored entries
-  #   stats(user_id:)                -> counts and metadata
+  #   read(query, user_id:, limit:)          -> relevant entries (retrieval)
+  #   write(payload, ...)                    -> ingest into the store (learning)
+  #   list(user_id:, limit:, offset:)        -> enumerate stored entries (paginated)
+  #   stats(user_id:)                        -> counts and metadata
   #
   # `read` defaults to the de-facto `search_candidates` interface the retrieval
   # Engine already relies on. `write`, `list` and `stats` are implemented by each
@@ -30,7 +30,7 @@ module Llmemory
       raise NotImplementedError, "#{self.class} must implement #write"
     end
 
-    def list(user_id: nil, limit: nil)
+    def list(user_id: nil, limit: nil, offset: nil)
       raise NotImplementedError, "#{self.class} must implement #list"
     end
 
@@ -40,9 +40,16 @@ module Llmemory
 
     # Removes entries by id (the same ids returned by #read) and records the
     # removal in a ForgetLog audit. Returns the number of entries removed.
+    #
+    # mode:
+    #   :soft (default) — soft-archive: entries are excluded from list/search/
+    #     retrieval but remain accessible by id (think "trash"). Reversible if
+    #     the store supports it.
+    #   :hard           — physical deletion. Irreversible.
+    #
     # Implemented by stores with a clear deletion model; others may not support
     # it (CoALA-style "unlearning" is understudied; deletion semantics differ).
-    def forget(ids:, reason: nil)
+    def forget(ids:, reason: nil, mode: :soft)
       raise NotImplementedError, "#{self.class} does not support #forget"
     end
 

data/lib/llmemory/reflection/reflector.rb

@@ -30,27 +30,31 @@ module Llmemory
       # Reflects over the most recent `window` episodes and writes the resulting
       # insights to semantic memory. Returns the ids of the stored insights.
       def reflect(window: 10, category: DEFAULT_CATEGORY)
-        episodes = @episodic.recent_episodes(limit: window)
-        return [] if episodes.empty?
-
-        insights = distill(episodes)
-        return [] if insights.empty?
-
-        sources = episodes.map(&:id).compact.map { |id| { type: "episode", id: id } }
-
-        insights.filter_map do |insight|
-          provenance = Llmemory::Provenance.build(
-            method: "reflection",
-            sources: sources,
-            confidence: insight[:confidence]
-          )
-          @semantic.remember_fact(
-            content: insight[:content],
-            category: category,
-            importance: insight[:confidence] || DEFAULT_IMPORTANCE,
-            provenance: provenance
-          )
+        result = []
+        Llmemory::Instrumentation.instrument(:reflect, window: window, category: category) do
+          episodes = @episodic.recent_episodes(limit: window)
+          next if episodes.empty?
+
+          insights = distill(episodes)
+          next if insights.empty?
+
+          sources = episodes.map(&:id).compact.map { |id| { type: "episode", id: id } }
+
+          result = insights.filter_map do |insight|
+            provenance = Llmemory::Provenance.build(
+              method: "reflection",
+              sources: sources,
+              confidence: insight[:confidence]
+            )
+            @semantic.remember_fact(
+              content: insight[:content],
+              category: category,
+              importance: insight[:confidence] || DEFAULT_IMPORTANCE,
+              provenance: provenance
+            )
+          end
         end
+        result
       end
 
       private

data/lib/llmemory/retrieval/engine.rb

@@ -24,9 +24,13 @@ module Llmemory
 
       def retrieve_for_inference(user_message, user_id: nil, max_tokens: nil)
         user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
-        search_query = generate_query(user_message)
-        ranked = ranked_candidates(search_query, user_id, user_message)
-        @assembler.assemble(ranked, max_tokens: max_tokens)
+        result = nil
+        Llmemory::Instrumentation.instrument(:retrieve, user_id: user_id, query_chars: user_message.to_s.length) do
+          search_query = generate_query(user_message)
+          ranked = ranked_candidates(search_query, user_id, user_message)
+          result = @assembler.assemble(ranked, max_tokens: max_tokens)
+        end
+        result
       end
 
       # Multi-hop retrieval (CoALA: integrating retrieval and reasoning). After
@@ -42,21 +46,26 @@ module Llmemory
         user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
         reasoner ||= method(:default_followup_query)
 
-        query = generate_query(user_message)
-        seen = []
-        accumulated = []
-        hop = 0
-
-        while hop < max_hops && live_query?(query) && !seen.include?(query)
-          seen << query
-          accumulated = merge_candidates(accumulated, ranked_candidates(query, user_id, query))
-          hop += 1
-          break if hop >= max_hops
+        final = nil
+        hops_done = 0
+        Llmemory::Instrumentation.instrument(:iterative_retrieve, user_id: user_id, query_chars: user_message.to_s.length, max_hops: max_hops) do
+          query = generate_query(user_message)
+          seen = []
+          accumulated = []
+          hop = 0
+
+          while hop < max_hops && live_query?(query) && !seen.include?(query)
+            seen << query
+            accumulated = merge_candidates(accumulated, ranked_candidates(query, user_id, query))
+            hop += 1
+            break if hop >= max_hops
+
+            query = reasoner.call(user_message, accumulated, hop).to_s.strip
+          end
+          hops_done = hop
 
-          query = reasoner.call(user_message, accumulated, hop).to_s.strip
+          final = accumulated.sort_by { |c| -(c[:temporal_score] || c[:score] || 0) }
         end
-
-        final = accumulated.sort_by { |c| -(c[:temporal_score] || c[:score] || 0) }
         @assembler.assemble(final, max_tokens: max_tokens)
       end
 

data/lib/llmemory/skill_mining/miner.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Llmemory
+  module SkillMining
+    # Skill mining scans an agent's recent episodes (episodic memory) for
+    # repeated, successful trajectories and distills them into reusable skills
+    # (procedural memory). This is Voyager's actual contribution: rather than a
+    # passive, hand-written skill library, procedural memory grows from lived
+    # experience.
+    #
+    # Mining is human-in-the-loop by default: `mine` returns skill *proposals*
+    # and writes nothing. Pass `auto_register: true` to register them directly.
+    # Each registered skill carries provenance { method: "skill_mining",
+    # sources: [{ type: "episode", id: ... }] } so it stays traceable to the
+    # experiences it was distilled from.
+    #
+    # `procedural` must respond to:
+    #   register_skill(name:, body:, description:, kind:, provenance:)
+    class Miner
+      DEFAULT_WINDOW = 20
+      DEFAULT_CONFIDENCE = 0.5
+      VALID_KINDS = %w[prompt template code].freeze
+
+      def initialize(episodic:, procedural:, llm: nil)
+        @episodic = episodic
+        @procedural = procedural
+        @llm = llm || Llmemory::LLM.client
+      end
+
+      # Mines the most recent `window` episodes for reusable skills. When
+      # `outcomes` (an allowlist of outcome labels) is given, only episodes whose
+      # outcome is in the set are considered — a deterministic pre-filter.
+      #
+      # Returns an array of proposal hashes
+      # ({ name:, kind:, body:, description:, confidence: }). When
+      # `auto_register: true`, registers each proposal and returns the new skill
+      # ids instead.
+      def mine(window: DEFAULT_WINDOW, outcomes: nil, auto_register: false)
+        result = []
+        Llmemory::Instrumentation.instrument(:mine_skills, window: window, auto_register: auto_register) do
+          episodes = @episodic.recent_episodes(limit: window)
+          episodes = filter_by_outcome(episodes, outcomes) if outcomes
+          next if episodes.empty?
+
+          proposals = distill(episodes)
+          next if proposals.empty?
+
+          result = auto_register ? register(proposals, episodes) : proposals
+        end
+        result
+      end
+
+      private
+
+      def filter_by_outcome(episodes, outcomes)
+        allowed = Array(outcomes).map { |o| o.to_s.strip.downcase }
+        episodes.select { |ep| allowed.include?(ep.outcome.to_s.strip.downcase) }
+      end
+
+      def register(proposals, episodes)
+        sources = episodes.map(&:id).compact.map { |id| { type: "episode", id: id } }
+        proposals.map do |p|
+          provenance = Llmemory::Provenance.build(
+            method: "skill_mining",
+            sources: sources,
+            confidence: p[:confidence]
+          )
+          @procedural.register_skill(
+            name: p[:name],
+            body: p[:body],
+            description: p[:description],
+            kind: p[:kind],
+            provenance: provenance
+          )
+        end
+      end
+
+      def distill(episodes)
+        response = @llm.invoke(build_prompt(episodes))
+        parse_proposals(response)
+      rescue Llmemory::LLMError
+        []
+      end
+
+      def build_prompt(episodes)
+        episodes_text = episodes.each_with_index.map do |ep, i|
+          "Episode #{i + 1} (outcome: #{ep.outcome || 'n/a'}):\n#{ep.searchable_text}"
+        end.join("\n\n")
+
+        <<~PROMPT
+          You are mining an agent's recent experiences for reusable skills. A skill
+          is a repeatable procedure the agent can apply again: a prompt, a template,
+          or a snippet of code. Only propose a skill when you see a SUCCESSFUL
+          pattern that recurs across episodes — generalize the steps into a reusable
+          procedure. Do not propose one-off actions or failures.
+
+          Recent episodes:
+          #{episodes_text}
+
+          Return a JSON array of objects with keys:
+            "name" (short snake_case identifier),
+            "kind" (one of "prompt", "template", "code"),
+            "body" (the reusable procedure itself),
+            "description" (one sentence on when to apply it),
+            "confidence" (0-1).
+          Return an empty array if no reusable skill can be distilled.
+          Example: [{"name": "rollback_on_deploy_failure", "kind": "prompt",
+          "body": "When a deploy fails, roll back to the last known-good release.",
+          "description": "Recover service after a failed deploy", "confidence": 0.8}]
+        PROMPT
+      end
+
+      def parse_proposals(response)
+        json = extract_json_array(response)
+        return [] unless json
+
+        json.filter_map do |item|
+          next nil unless item.is_a?(Hash)
+          name = (item["name"] || item[:name]).to_s.strip
+          body = (item["body"] || item[:body]).to_s.strip
+          next nil if name.empty? || body.empty?
+
+          {
+            name: name,
+            kind: normalize_kind(item["kind"] || item[:kind]),
+            body: body,
+            description: presence(item["description"] || item[:description]),
+            confidence: normalize_confidence(item["confidence"] || item[:confidence])
+          }
+        end
+      end
+
+      def normalize_kind(value)
+        k = value.to_s.strip.downcase
+        VALID_KINDS.include?(k) ? k : "prompt"
+      end
+
+      def normalize_confidence(value)
+        return DEFAULT_CONFIDENCE if value.nil?
+        v = value.to_f
+        v.between?(0, 1) ? v : DEFAULT_CONFIDENCE
+      end
+
+      def presence(value)
+        s = value.to_s.strip
+        s.empty? ? nil : s
+      end
+
+      def extract_json_array(response)
+        response = response.to_s.strip
+        start_idx = response.index("[")
+        end_idx = response.rindex("]")
+        return nil unless start_idx && end_idx
+
+        JSON.parse(response[start_idx..end_idx])
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/llmemory/skill_mining.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "skill_mining/miner"
+
+module Llmemory
+  module SkillMining
+  end
+end