llmemory 0.2.0 → 0.2.1

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+require_relative "base"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      module Storages
+        # ActiveRecord backend. Stores each skill as a JSONB `data` document; AR
+        # auto-deserializes jsonb to a Hash (string keys), which Skill.from_h
+        # handles. Mirrors the file-based ActiveRecordStorage pattern.
+        class ActiveRecordStorage < Base
+          def initialize
+            self.class.load_models!
+          end
+
+          def self.load_models!
+            return if @models_loaded
+            require "active_record"
+            require_relative "active_record_models"
+            @models_loaded = true
+          end
+
+          def save_skill(user_id, skill)
+            id = skill[:id] || skill["id"] || "skill_#{SecureRandom.hex(8)}"
+            data = stringify(skill).merge("id" => id, "user_id" => user_id)
+            data["created_at"] ||= Time.now.utc.iso8601
+            rec = LlmemorySkill.find_or_initialize_by(id: id)
+            rec.user_id = user_id
+            rec.data = data
+            rec.search_text = searchable_text(data)
+            rec.created_at ||= Time.current
+            rec.save!
+            id
+          end
+
+          def get_skill(user_id, id)
+            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)
+            scope = scope.limit(limit) if limit && limit.to_i.positive?
+            scope.map(&:data)
+          end
+
+          def search_skills(user_id, query)
+            token_scope(LlmemorySkill.where(user_id: user_id), "search_text", query)
+              .order(created_at: :desc).map(&:data)
+          end
+
+          def find_skills_by_name(user_id, name)
+            LlmemorySkill.where(user_id: user_id).where("data->>'name' = ?", name.to_s).map(&:data)
+          end
+
+          def record_outcome(user_id, skill_id, success:)
+            rec = LlmemorySkill.find_by(user_id: user_id, id: skill_id)
+            return nil unless rec
+            data = rec.data || {}
+            key = success ? "success_count" : "failure_count"
+            data[key] = (data[key] || 0).to_i + 1
+            data["updated_at"] = Time.now.utc.iso8601
+            rec.data = data
+            rec.search_text = searchable_text(data)
+            rec.save!
+            data
+          end
+
+          def count_skills(user_id)
+            LlmemorySkill.where(user_id: user_id).count
+          end
+
+          def delete_skills(user_id, ids)
+            LlmemorySkill.where(user_id: user_id, id: Array(ids).map(&:to_s)).delete_all
+          end
+
+          def list_users
+            LlmemorySkill.distinct.pluck(:user_id)
+          end
+
+          private
+
+          def token_scope(scope, column, query)
+            tokens = Llmemory::Tokenizer.tokenize(query)
+            return scope if tokens.empty?
+            clause = tokens.map { "LOWER(#{column}) LIKE LOWER(?)" }.join(" OR ")
+            scope.where(clause, *tokens.map { |t| "%#{t}%" })
+          end
+
+          def stringify(hash)
+            JSON.parse(JSON.generate(hash))
+          end
+
+          def searchable_text(data)
+            [data["name"], data["description"], data["body"]].compact.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+require_relative "base"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      module Storages
+        # PostgreSQL backend. Each skill is stored as a JSONB `data` document
+        # (plus id/user_id/created_at and a denormalized search_text), mirroring
+        # the file-based DatabaseStorage pattern.
+        class DatabaseStorage < Base
+          def initialize(database_url: nil)
+            @database_url = database_url || Llmemory.configuration.database_url
+            @connection = nil
+          end
+
+          def save_skill(user_id, skill)
+            ensure_tables!
+            id = skill[:id] || skill["id"] || "skill_#{SecureRandom.hex(8)}"
+            data = symbolize(skill).merge(id: id, user_id: user_id)
+            data[:created_at] ||= Time.now.utc.iso8601
+            conn.exec_params(
+              "INSERT INTO llmemory_skills (id, user_id, data, search_text, created_at) " \
+              "VALUES ($1, $2, $3::jsonb, $4, $5) " \
+              "ON CONFLICT (id) DO UPDATE SET data = $3::jsonb, search_text = $4",
+              [id, user_id, JSON.generate(data), searchable_text(data), created_at_value(data)]
+            )
+            id
+          end
+
+          def get_skill(user_id, id)
+            ensure_tables!
+            rows = conn.exec_params("SELECT data FROM llmemory_skills WHERE user_id = $1 AND id = $2", [user_id, id])
+            rows.any? ? parse_data(rows.first["data"]) : nil
+          end
+
+          def list_skills(user_id, limit: nil)
+            ensure_tables!
+            sql = "SELECT data FROM llmemory_skills WHERE user_id = $1 ORDER BY created_at DESC"
+            sql += " LIMIT #{limit.to_i}" if limit && limit.to_i.positive?
+            conn.exec_params(sql, [user_id]).map { |r| parse_data(r["data"]) }
+          end
+
+          def search_skills(user_id, query)
+            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",
+              [user_id, *params]
+            ).map { |r| parse_data(r["data"]) }
+          end
+
+          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",
+              [user_id, name.to_s]
+            ).map { |r| parse_data(r["data"]) }
+          end
+
+          def record_outcome(user_id, skill_id, success:)
+            ensure_tables!
+            data = get_skill(user_id, skill_id)
+            return nil unless data
+            key = success ? :success_count : :failure_count
+            data[key] = (data[key] || 0).to_i + 1
+            data[:updated_at] = Time.now.utc.iso8601
+            conn.exec_params(
+              "UPDATE llmemory_skills SET data = $3::jsonb, search_text = $4 WHERE user_id = $1 AND id = $2",
+              [user_id, skill_id, JSON.generate(data), searchable_text(data)]
+            )
+            data
+          end
+
+          def count_skills(user_id)
+            ensure_tables!
+            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_skills WHERE user_id = $1", [user_id]).first["c"].to_i
+          end
+
+          def delete_skills(user_id, ids)
+            ensure_tables!
+            Array(ids).sum do |id|
+              conn.exec_params("DELETE FROM llmemory_skills WHERE user_id = $1 AND id = $2", [user_id, id]).cmd_tuples
+            end
+          end
+
+          def list_users
+            ensure_tables!
+            conn.exec("SELECT DISTINCT user_id FROM llmemory_skills").map { |r| r["user_id"] }
+          end
+
+          private
+
+          def conn
+            @connection ||= begin
+              require "pg"
+              PG.connect(@database_url)
+            end
+          end
+
+          def ensure_tables!
+            conn.exec(<<~SQL)
+              CREATE TABLE IF NOT EXISTS llmemory_skills (
+                id TEXT NOT NULL PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                data JSONB NOT NULL DEFAULT '{}'::jsonb,
+                search_text TEXT,
+                created_at TIMESTAMPTZ NOT NULL
+              );
+              CREATE INDEX IF NOT EXISTS idx_llmemory_skills_user_id ON llmemory_skills(user_id);
+            SQL
+          end
+
+          def token_filter(column, query, start_index)
+            tokens = Llmemory::Tokenizer.tokenize(query)
+            return ["", []] if tokens.empty?
+            likes = tokens.each_index.map { |i| "LOWER(#{column}) LIKE $#{start_index + i}" }
+            [" AND (#{likes.join(' OR ')})", tokens.map { |t| "%#{t}%" }]
+          end
+
+          def parse_data(value)
+            JSON.parse(value.to_s, symbolize_names: true)
+          rescue JSON::ParserError
+            {}
+          end
+
+          def symbolize(hash)
+            hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+          end
+
+          def searchable_text(data)
+            [data[:name], data[:description], data[:body]].compact.join("\n")
+          end
+
+          def created_at_value(data)
+            ca = data[:created_at]
+            return Time.now.utc.iso8601 if ca.nil?
+            ca.respond_to?(:iso8601) ? ca.iso8601 : ca.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -35,9 +35,8 @@ module Llmemory
           end
 
           def search_skills(user_id, query)
-            q = query.to_s.downcase
-            return list_skills(user_id) if q.strip.empty?
-            all_skills(user_id).select { |s| skill_text(s).downcase.include?(q) }
+            return list_skills(user_id) if query.to_s.strip.empty?
+            all_skills(user_id).select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
           end
 
           def find_skills_by_name(user_id, name)

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

@@ -31,9 +31,8 @@ module Llmemory
           end
 
           def search_skills(user_id, query)
-            q = query.to_s.downcase
-            return list_skills(user_id) if q.strip.empty?
-            @skills[user_id].select { |s| skill_text(s).downcase.include?(q) }
+            return list_skills(user_id) if query.to_s.strip.empty?
+            @skills[user_id].select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
           end
 
           def find_skills_by_name(user_id, name)

data/lib/llmemory/mcp/server.rb

@@ -11,6 +11,12 @@ require_relative "tools/memory_consolidate"
 require_relative "tools/memory_stats"
 require_relative "tools/memory_info"
 require_relative "tools/memory_timeline_context"
+require_relative "tools/memory_episode_record"
+require_relative "tools/memory_episodes"
+require_relative "tools/memory_skill_register"
+require_relative "tools/memory_skill_report"
+require_relative "tools/memory_skills"
+require_relative "tools/memory_forget"
 
 module Llmemory
   module MCP
@@ -157,7 +163,13 @@ module Llmemory
           Tools::MemoryAddMessage,
           Tools::MemoryConsolidate,
           Tools::MemoryStats,
-          Tools::MemoryInfo
+          Tools::MemoryInfo,
+          Tools::MemoryEpisodeRecord,
+          Tools::MemoryEpisodes,
+          Tools::MemorySkillRegister,
+          Tools::MemorySkillReport,
+          Tools::MemorySkills,
+          Tools::MemoryForget
         ]
       end
 

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryEpisodeRecord < ::MCP::Tool
+        description "Record an experience (episodic memory): a trajectory of steps with an optional summary, outcome and importance. Use to remember what just happened so it can be retrieved or distilled into knowledge later."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            steps: {
+              type: "array",
+              description: "Ordered list of steps (objects with observation/action/result)",
+              items: {
+                type: "object",
+                properties: {
+                  observation: { type: "string" },
+                  action: { type: "string" },
+                  result: { type: "string" }
+                }
+              }
+            },
+            summary: { type: "string", description: "Optional summary (derived from steps if omitted)" },
+            outcome: { type: "string", description: "Outcome label, e.g. 'success', 'failure', 'recovered'" },
+            importance: { type: "number", description: "Importance 0-1 (default 0.5)" }
+          },
+          required: ["user_id", "steps"]
+        )
+
+        class << self
+          def call(user_id:, steps:, summary: nil, outcome: nil, importance: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            id = memory.record_episode(
+              steps: Array(steps),
+              summary: summary,
+              outcome: outcome,
+              importance: importance.nil? ? 0.5 : importance.to_f
+            )
+            ::MCP::Tool::Response.new([{ type: "text", text: "Episode recorded: #{id}" }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error recording episode: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryEpisodes < ::MCP::Tool
+        description "List recent episodes (episodic memory) for a user. Optionally filter by a keyword query."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            query: { type: "string", description: "Optional keyword filter" },
+            limit: { type: "integer", description: "Max episodes to return (default 10)" }
+          },
+          required: ["user_id"]
+        )
+
+        class << self
+          def call(user_id:, query: nil, limit: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            cap = (limit || 10).to_i
+            episodes = if query.to_s.strip.empty?
+              memory.recent_episodes(limit: cap)
+            else
+              memory.search_candidates(query, top_k: cap).filter_map { |c| memory.find_episode(c[:id]) }
+            end
+
+            if episodes.empty?
+              return ::MCP::Tool::Response.new([{ type: "text", text: "No episodes for user #{user_id}." }])
+            end
+
+            lines = episodes.map do |ep|
+              "[#{ep.id}] (importance: #{ep.importance}; outcome: #{ep.outcome || 'n/a'}) #{ep.summary || ep.searchable_text[0, 120]}"
+            end
+            ::MCP::Tool::Response.new([{ type: "text", text: lines.join("\n") }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error listing episodes: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryForget < ::MCP::Tool
+        description "Remove entries from a memory by their ids (the ids returned by retrieval / listing tools), recording the removal in the audit log. memory_type: file_based | graph_based | episodic | procedural."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            memory_type: { type: "string", description: "file_based | graph_based | episodic | procedural" },
+            ids: { type: "array", items: { type: "string" }, description: "Entry ids to forget" },
+            reason: { type: "string", description: "Optional reason (recorded in audit)" }
+          },
+          required: ["user_id", "memory_type", "ids"]
+        )
+
+        class << self
+          def call(user_id:, memory_type:, ids:, reason: nil, server_context: nil)
+            memory = build_memory(user_id, memory_type)
+            removed = memory.forget(ids: Array(ids), reason: reason)
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: "Forgot #{removed} entries from #{memory_type} memory for user #{user_id}."
+            }])
+          rescue NotImplementedError => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Not supported: #{e.message}" }], error: true)
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error forgetting: #{e.message}" }], error: true)
+          end
+
+          private
+
+          def build_memory(user_id, memory_type)
+            case memory_type.to_s
+            when "file_based"
+              Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id)
+            when "graph_based"
+              Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id)
+            when "episodic"
+              Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            when "procedural"
+              Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            else
+              raise ArgumentError, "Unknown memory_type: #{memory_type} (expected file_based|graph_based|episodic|procedural)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -59,8 +59,10 @@ module Llmemory
             items = storage.search_items(user_id, query)
             return "" if items.empty?
 
-            # Get timeline context around the first match
-            top_item = items.first
+            # Anchor on the most precise match: keyword search is recall-oriented
+            # (tokenized OR), so prefer the item whose content contains the full
+            # query verbatim, falling back to the first match.
+            top_item = best_match(items, query)
             item_id = top_item[:id] || top_item["id"]
             return "" unless item_id
 
@@ -70,6 +72,12 @@ module Llmemory
             ""
           end
 
+          def best_match(items, query)
+            q = query.to_s.downcase.strip
+            return items.first if q.empty?
+            items.find { |i| (i[:content] || i["content"]).to_s.downcase.include?(q) } || items.first
+          end
+
           def build_storage
             if Llmemory.configuration.long_term_type.to_s == "graph_based"
               LongTerm::GraphBased::Storages.build

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemorySkillRegister < ::MCP::Tool
+        description "Register a reusable skill (procedural memory): a prompt, template or code snippet the agent can retrieve later. Re-registering the same name auto-increments the version."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            name: { type: "string", description: "Short identifier (skills with the same name get auto-versioned)" },
+            body: { type: "string", description: "The skill content (prompt / template / code)" },
+            description: { type: "string", description: "Optional human-readable description" },
+            kind: { type: "string", description: "prompt | template | code (default: prompt)" }
+          },
+          required: ["user_id", "name", "body"]
+        )
+
+        class << self
+          def call(user_id:, name:, body:, description: nil, kind: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            id = memory.register_skill(
+              name: name, body: body, description: description,
+              kind: kind || Llmemory::LongTerm::Procedural::Skill::DEFAULT_KIND
+            )
+            ::MCP::Tool::Response.new([{ type: "text", text: "Skill registered: #{id} (#{name})" }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error registering skill: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemorySkillReport < ::MCP::Tool
+        description "Report the outcome of applying a skill (success or failure). Feeds retrieval ranking: proven skills surface higher next time."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            skill_id: { type: "string", description: "Skill id (from MemorySkillRegister / MemorySkills)" },
+            success: { type: "boolean", description: "True if the skill worked; false otherwise" }
+          },
+          required: ["user_id", "skill_id", "success"]
+        )
+
+        class << self
+          def call(user_id:, skill_id:, success:, server_context: nil)
+            memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            skill = memory.report_outcome(skill_id, success: success == true)
+            if skill.nil?
+              return ::MCP::Tool::Response.new([{ type: "text", text: "Skill not found: #{skill_id}" }], error: true)
+            end
+
+            text = "Outcome recorded for #{skill.name} (#{skill_id}): success #{skill.success_count} / failure #{skill.failure_count} (rate #{format('%.2f', skill.success_rate)})"
+            ::MCP::Tool::Response.new([{ type: "text", text: text }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error reporting outcome: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemorySkills < ::MCP::Tool
+        description "List registered skills (procedural memory) for a user, ranked by proven utility when a query is given."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            query: { type: "string", description: "Optional keyword to filter skills" },
+            limit: { type: "integer", description: "Max skills to return (default 10)" }
+          },
+          required: ["user_id"]
+        )
+
+        class << self
+          def call(user_id:, query: nil, limit: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            cap = (limit || 10).to_i
+            skills = if query.to_s.strip.empty?
+              memory.skills(limit: cap)
+            else
+              memory.search_candidates(query, top_k: cap).filter_map { |c| memory.get_skill(c[:id]) }
+            end
+
+            if skills.empty?
+              return ::MCP::Tool::Response.new([{ type: "text", text: "No skills for user #{user_id}." }])
+            end
+
+            lines = skills.map do |s|
+              "[#{s.id}] #{s.name} v#{s.version} (#{s.kind}) — success rate #{format('%.2f', s.success_rate)} (#{s.success_count}/#{s.success_count + s.failure_count})"
+            end
+            ::MCP::Tool::Response.new([{ type: "text", text: lines.join("\n") }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error listing skills: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/memory.rb

@@ -10,11 +10,13 @@ module Llmemory
     DEFAULT_SESSION_ID = "default"
     STATE_KEY_MESSAGES = :messages
 
-    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, checkpoint: nil, long_term: nil, long_term_type: nil, retrieval_engine: nil, working_memory: nil, api_key: nil)
+    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, checkpoint: nil, long_term: nil, long_term_type: nil, retrieval_engine: nil, working_memory: nil, episodic: nil, procedural: nil, api_key: nil)
       @user_id = user_id
       @session_id = session_id
       @checkpoint = checkpoint || ShortTerm::Checkpoint.new(user_id: user_id, session_id: session_id)
       @working_memory = working_memory
+      @episodic = episodic
+      @procedural = procedural
       @llm = api_key.to_s.empty? ? nil : Llmemory::LLM.client(api_key: api_key)
       type = long_term_type || Llmemory.configuration.long_term_type || :file_based
       @long_term = long_term || build_long_term(type)
@@ -22,12 +24,35 @@ module Llmemory
     end
 
     # Structured working memory for this session (CoALA working memory),
-    # parallel to the message checkpoint. Lazily built so it costs nothing
-    # unless an agent uses it.
+    # parallel to the message checkpoint. Lazily built.
     def working_memory
       @working_memory ||= WorkingMemory.new(user_id: @user_id, session_id: @session_id)
     end
 
+    # Episodic long-term memory (CoALA): records and retrieves agent trajectories.
+    # Additive — coexists with the semantic store (file/graph). Lazily built.
+    def episodic
+      @episodic ||= LongTerm::Episodic::Memory.new(user_id: @user_id)
+    end
+
+    # Procedural long-term memory (Voyager-style skill library). Lazily built.
+    def procedural
+      @procedural ||= LongTerm::Procedural::Memory.new(user_id: @user_id)
+    end
+
+    # Reflects over recent episodes and writes distilled insights to the
+    # semantic store (file/graph) with provenance back to source episodes.
+    def reflect!(window: 10, category: "insights")
+      Reflection::Reflector.new(episodic: episodic, semantic: @long_term, llm: @llm)
+        .reflect(window: window, category: category)
+    end
+
+    # Reasoning action: render a prompt from working memory, call the LLM, write
+    # the result back. Composable; does not touch long-term memory.
+    def reason(template:, into: Actions::Reason::DEFAULT_SLOT, parse: nil)
+      Actions::Reason.call(working_memory: working_memory, template: template, into: into, parse: parse, llm: @llm)
+    end
+
     def add_message(role:, content:)
       msgs = messages
       msgs << { role: role.to_sym, content: content.to_s }

data/lib/llmemory/retrieval/bm25_scorer.rb

@@ -53,7 +53,7 @@ module Llmemory
       private
 
       def tokenize(text)
-        text.to_s.downcase.scan(/\b[a-z0-9]{2,}\b/)
+        Llmemory::Tokenizer.tokenize(text)
       end
     end
   end

data/lib/llmemory/retrieval/mmr_reranker.rb

@@ -49,7 +49,7 @@ module Llmemory
       end
 
       def tokenize(text)
-        text.downcase.scan(/\b[a-z0-9]{2,}\b/).uniq
+        Llmemory::Tokenizer.tokenize(text).uniq
       end
     end
   end