llmemory 0.2.0 → 0.2.2

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Episodic < Commands::Base
+        def option_parser(parser)
+          parser.on("--limit N", Integer, "Max number of episodes (newest first)") { |v| @limit = 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 episodes USER_ID [--limit N] [--store TYPE]"
+            exit 1
+          end
+
+          storage = episodic_storage(@store_type)
+          episodes = storage.list_episodes(user_id, limit: @limit)
+
+          if episodes.empty?
+            puts "No episodes for user #{user_id}."
+            return
+          end
+
+          episodes.each do |e|
+            id = e[:id] || e["id"]
+            summary = e[:summary] || e["summary"]
+            outcome = e[:outcome] || e["outcome"]
+            importance = e[:importance] || e["importance"]
+            steps = e[:steps] || e["steps"] || []
+            puts "[#{id}] (importance: #{importance}; outcome: #{outcome || 'n/a'}) #{summary}"
+            puts "  steps: #{Array(steps).size}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class ForgetLog < Commands::Base
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory forget-log USER_ID"
+            exit 1
+          end
+
+          entries = Llmemory::ForgetLog.new(store: short_term_store).entries(user_id)
+
+          if entries.empty?
+            puts "No forget audit entries for user #{user_id}."
+            return
+          end
+
+          entries.each do |e|
+            type = e[:memory_type] || e["memory_type"]
+            count = e[:count] || e["count"]
+            reason = e[:reason] || e["reason"]
+            at = e[:at] || e["at"]
+            ids = e[:ids] || e["ids"] || []
+            reason_str = reason ? " — #{reason}" : ""
+            puts "[#{at}] #{type}: removed #{count} (#{ids.join(', ')})#{reason_str}"
+          end
+        end
+      end
+    end
+  end
+end

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/commands/procedural.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Procedural < Commands::Base
+        def option_parser(parser)
+          parser.on("--limit N", Integer, "Max number of skills (newest first)") { |v| @limit = 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 skills USER_ID [--limit N] [--store TYPE]"
+            exit 1
+          end
+
+          storage = procedural_storage(@store_type)
+          skills = storage.list_skills(user_id, limit: @limit)
+
+          if skills.empty?
+            puts "No skills for user #{user_id}."
+            return
+          end
+
+          skills.each do |s|
+            id = s[:id] || s["id"]
+            name = s[:name] || s["name"]
+            kind = s[:kind] || s["kind"]
+            version = s[:version] || s["version"]
+            succ = (s[:success_count] || s["success_count"] || 0).to_i
+            fail = (s[:failure_count] || s["failure_count"] || 0).to_i
+            total = succ + fail
+            rate = total.zero? ? "n/a" : format("%.2f", succ.to_f / total)
+            puts "[#{id}] #{name} v#{version} (#{kind}) — success rate: #{rate} (#{succ}/#{total})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Working < Commands::Base
+        def execute(argv, _opts)
+          user_id, session_id = argv
+          unless user_id && session_id
+            $stderr.puts "Usage: llmemory working USER_ID SESSION_ID"
+            exit 1
+          end
+
+          wm = Llmemory::WorkingMemory.new(user_id: user_id, session_id: session_id, store: short_term_store)
+          state = wm.to_h
+
+          if state.empty?
+            puts "Empty working memory for user #{user_id}, session #{session_id}."
+            return
+          end
+
+          state.each do |slot, value|
+            puts "#{slot}: #{value.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli.rb

@@ -5,6 +5,12 @@ require_relative "cli/commands/base"
 require_relative "cli/commands/users"
 require_relative "cli/commands/short_term"
 require_relative "cli/commands/long_term"
+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"
@@ -47,6 +53,12 @@ module Llmemory
         "nodes" => Cli::Commands::LongTerm::Nodes,
         "edges" => Cli::Commands::LongTerm::Edges,
         "graph" => Cli::Commands::LongTerm::Graph,
+        "episodes" => Cli::Commands::Episodic,
+        "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
@@ -68,6 +80,12 @@ module Llmemory
           nodes USER_ID            List graph nodes (graph-based)
           edges USER_ID            List graph edges (graph-based)
           graph USER_ID            Export graph (--format dot|json)
+          episodes USER_ID         List recorded episodes (episodic memory)
+          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

@@ -11,6 +11,8 @@ module Llmemory
                   :long_term_type,
                   :long_term_store,
                   :long_term_storage_path,
+                  :episodic_vector_enabled,
+                  :procedural_vector_enabled,
                   :database_url,
                   :vector_store,
                   :time_decay_half_life_days,
@@ -43,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
@@ -55,6 +60,11 @@ module Llmemory
       @long_term_type = :file_based
       @long_term_store = :memory
       @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

@@ -3,6 +3,7 @@
 require_relative "episode"
 require_relative "storage"
 require_relative "../../memory_module"
+require_relative "../../vector_store"
 
 module Llmemory
   module LongTerm
@@ -12,16 +13,19 @@ module Llmemory
       # memory (file/graph), not replace it, and to feed reflection (P2), which
       # distills episodes into semantic knowledge.
       #
-      # Deliberately LLM-free: recording and retrieval are deterministic. Higher
-      # order summarization belongs to reflection.
+      # Recording/retrieval are deterministic and LLM-free by default. Semantic
+      # (embedding) retrieval is opt-in via `config.episodic_vector_enabled` or by
+      # injecting a `vector_store:`; when off, search is keyword-only (unchanged).
       class Memory
         include Llmemory::MemoryModule
 
         attr_reader :user_id, :storage
 
-        def initialize(user_id:, storage: nil)
+        def initialize(user_id:, storage: nil, vector_store: nil)
           @user_id = user_id
           @storage = storage || Storages.build
+          @vector_store = vector_store
+          @vector_explicit = !vector_store.nil?
         end
 
         # Records a trajectory. `steps` is an array of hashes with any of
@@ -39,15 +43,17 @@ module Llmemory
             episode.searchable_text, method: "episode_recording", confidence: episode.importance
           )
           record = episode.to_h.merge(provenance: provenance)
-          @storage.save_episode(@user_id, record)
+          id = @storage.save_episode(@user_id, record)
+          index_vector(id, episode.searchable_text)
+          id
         end
 
         def recent_episodes(limit: 10)
           @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)
@@ -62,49 +68,111 @@ module Llmemory
         # Retrieval Engine integration. Returns candidates shaped like the other
         # long-term memories so the Engine can rank episodes by relevance,
         # recency (temporal decay) and importance (P3), with provenance (P10).
+        # Hybrid (vector + keyword) when a vector store is active; otherwise
+        # keyword-only.
         def search_candidates(query, user_id: nil, top_k: 20)
           uid = user_id || @user_id
           return [] unless uid == @user_id
 
-          @storage.search_episodes(uid, query).first(top_k).map do |e|
-            episode = Episode.from_h(e)
-            {
-              id: episode.id,
-              text: episode.summary.to_s.empty? ? episode.searchable_text : episode.summary,
-              timestamp: episode.created_at,
-              score: 1.0,
-              importance: episode.importance,
-              evergreen: false,
-              provenance: e[:provenance] || e["provenance"]
-            }
-          end
+          keyword = @storage.search_episodes(uid, query).first(top_k).map { |e| candidate_for(e, 1.0) }
+          vs = vector_store
+          return keyword unless vs
+
+          merge_candidates(vector_candidates(query, top_k, vs), keyword, top_k)
         end
 
         # --- 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
 
+        # Active vector store: the injected one, or a config-gated lazy build.
+        # Returns nil when semantic search is disabled (default).
+        def vector_store
+          if @vector_explicit
+            @vector_store
+          elsif Llmemory.configuration.episodic_vector_enabled
+            @vector_store ||= Llmemory::VectorStore.build(source_type: "episode")
+          end
+        end
+
+        # Best-effort embedding indexing; a failure must never break recording.
+        def index_vector(id, text)
+          vs = vector_store
+          return if vs.nil? || text.to_s.strip.empty?
+          embedding = vs.embed(text)
+          return unless embedding
+          vs.store(id: id, embedding: embedding, metadata: { text: text, created_at: Time.now }, user_id: @user_id)
+        rescue StandardError
+          nil
+        end
+
+        def vector_candidates(query, top_k, vs)
+          vs.search_by_text(query.to_s, top_k: top_k, user_id: @user_id).filter_map do |r|
+            raw = @storage.get_episode(@user_id, r[:id] || r["id"])
+            raw && candidate_for(raw, (r[:score] || r["score"] || 1.0).to_f)
+          end
+        rescue StandardError
+          []
+        end
+
+        def candidate_for(raw, score)
+          episode = Episode.from_h(raw)
+          {
+            id: episode.id,
+            text: episode.summary.to_s.empty? ? episode.searchable_text : episode.summary,
+            timestamp: episode.created_at,
+            score: score,
+            importance: episode.importance,
+            evergreen: false,
+            provenance: raw[:provenance] || raw["provenance"]
+          }
+        end
+
+        # Dedup by id keeping the higher score; highest score first, capped.
+        def merge_candidates(primary, secondary, top_k)
+          by_id = {}
+          (primary + secondary).each do |c|
+            key = c[:id] || c[:text]
+            existing = by_id[key]
+            by_id[key] = c if existing.nil? || c[:score].to_f > existing[:score].to_f
+          end
+          by_id.values.sort_by { |c| -c[:score].to_f }.first(top_k)
+        end
+
         # Cheap, deterministic summary when the caller does not provide one.
         # LLM-based summarization is reflection's job (P2).
         def derive_summary(steps)

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

@@ -3,6 +3,7 @@
 require_relative "storages/base"
 require_relative "storages/memory_storage"
 require_relative "storages/file_storage"
+require_relative "storages/database_storage"
 
 module Llmemory
   module LongTerm
@@ -11,16 +12,17 @@ module Llmemory
       Storage = Storages::MemoryStorage
 
       module Storages
-        def self.build(store: nil, base_path: nil)
+        def self.build(store: nil, base_path: nil, database_url: nil)
           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)
-          when :postgres, :database, :active_record, :activerecord
-            raise NotImplementedError,
-              "Episodic SQL/ActiveRecord storage is not implemented yet; use :memory or :file " \
-              "(or pass an explicit storage instance)."
+          when :postgres, :database
+            DatabaseStorage.new(database_url: database_url || Llmemory.configuration.database_url)
+          when :active_record, :activerecord
+            require_relative "storages/active_record_storage"
+            ActiveRecordStorage.new
           else
             MemoryStorage.new
           end