llmemory 0.1.17 → 0.2.1

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,16 +10,49 @@ 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, 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)
       @retrieval_engine = retrieval_engine || Retrieval::Engine.new(@long_term, llm: @llm)
     end
 
+    # Structured working memory for this session (CoALA working memory),
+    # 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/memory_module.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Llmemory
+  # Uniform contract for queryable long-term memories (file-based, graph-based,
+  # episodic). CoALA argues agents should be modular with standardized
+  # 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` defaults to the de-facto `search_candidates` interface the retrieval
+  # Engine already relies on. `write`, `list` and `stats` are implemented by each
+  # including class over its native API.
+  #
+  # Deliberately excluded: session-state stores (Checkpoint, WorkingMemory) are a
+  # different abstraction (K/V session state, not a retrievable corpus), and
+  # deletion/forgetting semantics are deferred to a coherent unlearning API.
+  module MemoryModule
+    def read(query, user_id: nil, limit: 20)
+      unless respond_to?(:search_candidates)
+        raise NotImplementedError, "#{self.class} must implement #read or #search_candidates"
+      end
+      search_candidates(query, user_id: user_id, top_k: limit)
+    end
+
+    def write(*, **)
+      raise NotImplementedError, "#{self.class} must implement #write"
+    end
+
+    def list(user_id: nil, limit: nil)
+      raise NotImplementedError, "#{self.class} must implement #list"
+    end
+
+    def stats(user_id: nil)
+      raise NotImplementedError, "#{self.class} must implement #stats"
+    end
+
+    # Removes entries by id (the same ids returned by #read) and records the
+    # removal in a ForgetLog audit. Returns the number of entries removed.
+    # 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)
+      raise NotImplementedError, "#{self.class} does not support #forget"
+    end
+
+    # Shared audit trail for #forget. Lazily built; override or inject by setting
+    # @forget_log if a specific backend/store is required.
+    def forget_log
+      @forget_log ||= Llmemory::ForgetLog.new
+    end
+  end
+end

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/engine.rb

@@ -4,34 +4,142 @@ require_relative "temporal_ranker"
 require_relative "context_assembler"
 require_relative "bm25_scorer"
 require_relative "mmr_reranker"
+require_relative "feedback_store"
 
 module Llmemory
   module Retrieval
     class Engine
       RELEVANCE_THRESHOLD = 0.7
+      FEEDBACK_CAP = 5
 
-      def initialize(memory, llm: nil)
+      def initialize(memory, llm: nil, feedback: nil)
         @memory = memory
         @llm = llm || Llmemory::LLM.client
         @ranker = TemporalRanker.new
         @assembler = ContextAssembler.new
         @bm25_scorer = Bm25Scorer.new
         @mmr_reranker = MmrReranker.new(lambda: Llmemory.configuration.mmr_lambda)
+        @feedback = feedback || FeedbackStore.new
       end
 
       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)
+      end
+
+      # Multi-hop retrieval (CoALA: integrating retrieval and reasoning). After
+      # each hop, a reasoner inspects what has been retrieved and proposes a
+      # follow-up query for the missing piece, enabling multi-hop questions a
+      # single retrieval would miss. Candidates accumulate (deduped) across hops.
+      #
+      # `reasoner` is a callable (user_message, accumulated_candidates, hop) ->
+      # next query String, or "DONE"/blank to stop. Defaults to an LLM that
+      # proposes the next sub-query. Converges on `max_hops`, "DONE", a blank
+      # query, or a repeated query.
+      def iterative_retrieve(user_message, user_id: nil, max_tokens: nil, max_hops: 2, reasoner: nil)
+        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
+
+          query = reasoner.call(user_message, accumulated, hop).to_s.strip
+        end
+
+        final = accumulated.sort_by { |c| -(c[:temporal_score] || c[:score] || 0) }
+        @assembler.assemble(final, max_tokens: max_tokens)
+      end
+
+      # Records that previously-retrieved items were useful or harmful for the
+      # agent's task. Repeatedly useful items rank higher in future retrievals;
+      # noisy ones are dampened. Item ids come from the candidates returned by
+      # the memory's #read / #search_candidates.
+      def report_feedback(useful_ids: [], harmful_ids: [], user_id: nil)
+        user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
+        Array(useful_ids).each { |id| @feedback.record(user_id, id, 1) }
+        Array(harmful_ids).each { |id| @feedback.record(user_id, id, -1) }
+        true
+      end
+
+      private
+
+      # One retrieval hop: fetch -> hybrid -> relevance filter -> temporal rank
+      # -> feedback adjust -> (optional) MMR. Returns ranked candidates.
+      def ranked_candidates(search_query, user_id, relevance_text)
         candidates = fetch_candidates(search_query, user_id)
         candidates = apply_hybrid_scoring(candidates, search_query) if Llmemory.configuration.hybrid_search_enabled
-
-        relevant = filter_by_relevance(candidates, user_message)
+        relevant = filter_by_relevance(candidates, relevance_text)
         ranked = @ranker.rank(relevant)
-        ranked = @mmr_reranker.rerank(ranked) if Llmemory.configuration.mmr_enabled
-        @assembler.assemble(ranked, max_tokens: max_tokens)
+        ranked = apply_feedback(ranked, user_id)
+        Llmemory.configuration.mmr_enabled ? @mmr_reranker.rerank(ranked) : ranked
       end
 
-      private
+      def live_query?(query)
+        !query.nil? && !query.to_s.strip.empty? && query.to_s.strip.upcase != "DONE"
+      end
+
+      def merge_candidates(accumulated, additions)
+        by_key = {}
+        (accumulated + additions).each do |c|
+          key = c[:id] || c[:text]
+          current = by_key[key]
+          if current.nil? || score_of(c) > score_of(current)
+            by_key[key] = c
+          end
+        end
+        by_key.values
+      end
+
+      def score_of(candidate)
+        (candidate[:temporal_score] || candidate[:score] || 0).to_f
+      end
+
+      def default_followup_query(user_message, accumulated, _hop)
+        context = accumulated.first(10).map { |c| c[:text] }.compact.join("\n")
+        prompt = <<~PROMPT
+          Question: #{user_message}
+          Information retrieved so far:
+          #{context}
+
+          If more information is needed to fully answer the question, reply with a
+          single short search query for the missing piece. If what was retrieved is
+          sufficient, reply with exactly "DONE".
+        PROMPT
+        @llm.invoke(prompt.strip).to_s.strip
+      rescue Llmemory::LLMError
+        "DONE"
+      end
+
+      def apply_feedback(ranked, user_id)
+        weight = Llmemory.configuration.retrieval_feedback_weight.to_f
+        return ranked if user_id.nil? || weight <= 0
+
+        adjusted = ranked.map do |c|
+          id = c[:id] || c["id"]
+          net = id.nil? ? 0 : @feedback.net(user_id, id)
+          next c if net.zero?
+
+          base = (c[:temporal_score] || c[:score] || 0).to_f
+          c.merge(temporal_score: base * feedback_factor(net, weight))
+        end
+        adjusted.sort_by { |c| -(c[:temporal_score] || 0) }
+      end
+
+      # Maps net feedback to a bounded multiplier in [1 - weight, 1 + weight].
+      def feedback_factor(net, weight)
+        capped = [[net, -FEEDBACK_CAP].max, FEEDBACK_CAP].min
+        1.0 + (weight * (capped.to_f / FEEDBACK_CAP))
+      end
 
       def generate_query(user_message)
         return user_message.to_s if user_message.to_s.length <= 100
@@ -51,6 +159,7 @@ module Llmemory
         raw = @memory.search_candidates(search_query, user_id: user_id, top_k: 20)
         raw.map do |c|
           {
+            id: c[:id] || c["id"],
             text: c[:text] || c["text"],
             timestamp: parse_timestamp(c[:timestamp] || c["timestamp"] || c[:created_at] || c["created_at"]),
             score: (c[:score] || c["score"] || 1.0).to_f,

data/lib/llmemory/retrieval/feedback_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../short_term/stores"
+
+module Llmemory
+  module Retrieval
+    # Persists retrieval feedback: a net utility signal per (user, memory item),
+    # accumulated from agents marking retrieved items useful (+1) or harmful (-1).
+    #
+    # CoALA flags adaptive retrieval — "learning better retrieval procedures" — as
+    # understudied. This is the minimal substrate for it: a feedback ledger the
+    # Engine consults to boost repeatedly-useful items and dampen noise.
+    #
+    # Backed by the same pluggable short-term stores as Checkpoint/WorkingMemory,
+    # under a per-user pseudo-session key.
+    class FeedbackStore
+      SESSION_KEY = "__retrieval_feedback__"
+
+      def initialize(store: nil)
+        @store = store || ShortTerm::Stores.build
+      end
+
+      def record(user_id, item_id, delta)
+        return if user_id.nil? || item_id.nil?
+        state = load(user_id)
+        key = item_id.to_s
+        state[key] = (state[key] || 0) + delta.to_i
+        @store.save(user_id, SESSION_KEY, state)
+        state[key]
+      end
+
+      def net(user_id, item_id)
+        return 0 if user_id.nil? || item_id.nil?
+        load(user_id)[item_id.to_s] || 0
+      end
+
+      def all(user_id)
+        load(user_id)
+      end
+
+      private
+
+      def load(user_id)
+        state = @store.load(user_id, SESSION_KEY)
+        return {} unless state.is_a?(Hash)
+        state.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_i }
+      end
+    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

data/lib/llmemory/short_term/checkpoint.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "stores/base"
-require_relative "stores/memory_store"
-require_relative "stores/redis_store"
-require_relative "stores/postgres_store"
+require_relative "stores"
 
 module Llmemory
   module ShortTerm
@@ -31,16 +28,7 @@ module Llmemory
       private
 
       def build_store
-        case Llmemory.configuration.short_term_store.to_sym
-        when :memory then Stores::MemoryStore.new
-        when :redis then Stores::RedisStore.new
-        when :postgres then Stores::PostgresStore.new
-        when :active_record, :activerecord
-          require_relative "stores/active_record_store"
-          Stores::ActiveRecordStore.new
-        else
-          Stores::MemoryStore.new
-        end
+        Stores.build
       end
     end
   end

data/lib/llmemory/short_term/session_lifecycle.rb

@@ -1,8 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "stores"
+
 module Llmemory
   module ShortTerm
     class SessionLifecycle
+      # Pseudo-sessions used by ForgetLog, FeedbackStore and WorkingMemory share
+      # the short-term K/V store but are not user sessions — they must not be
+      # idle-pruned, stale-pruned, or evicted by enforce_max_entries.
+      PSEUDO_SESSION_PATTERNS = [
+        /\A__[a-z_]+__\z/,    # e.g. "__forget_log__", "__retrieval_feedback__"
+        /:working_memory\z/    # WorkingMemory uses "<session>:working_memory"
+      ].freeze
+
+      def self.pseudo_session?(session_id)
+        PSEUDO_SESSION_PATTERNS.any? { |p| session_id.to_s.match?(p) }
+      end
+
       def initialize(store: nil)
         @store = store || build_store
       end
@@ -12,7 +26,7 @@ module Llmemory
         cutoff = Time.now - (idle_minutes * 60)
         deleted = 0
 
-        @store.list_sessions(user_id: user_id).each do |session_id|
+        user_sessions(user_id).each do |session_id|
           state = @store.load(user_id, session_id)
           next unless state.is_a?(Hash)
 
@@ -34,7 +48,7 @@ module Llmemory
         cutoff = Time.now - (prune_after_days * 86400)
         deleted = 0
 
-        @store.list_sessions(user_id: user_id).each do |session_id|
+        user_sessions(user_id).each do |session_id|
           state = @store.load(user_id, session_id)
           next unless state.is_a?(Hash)
 
@@ -53,7 +67,7 @@ module Llmemory
 
       def enforce_max_entries!(user_id:, max_entries: nil)
         max_entries ||= Llmemory.configuration.session_max_entries_per_user
-        sessions = @store.list_sessions(user_id: user_id)
+        sessions = user_sessions(user_id)
         return 0 if sessions.size <= max_entries
 
         session_ages = sessions.map do |session_id|
@@ -71,17 +85,12 @@ module Llmemory
 
       private
 
+      def user_sessions(user_id)
+        @store.list_sessions(user_id: user_id).reject { |s| self.class.pseudo_session?(s) }
+      end
+
       def build_store
-        case Llmemory.configuration.short_term_store.to_sym
-        when :memory then Stores::MemoryStore.new
-        when :redis then Stores::RedisStore.new
-        when :postgres then Stores::PostgresStore.new
-        when :active_record, :activerecord
-          require_relative "stores/active_record_store"
-          Stores::ActiveRecordStore.new
-        else
-          Stores::MemoryStore.new
-        end
+        Stores.build
       end
     end
   end

data/lib/llmemory/short_term/stores.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "stores/base"
+require_relative "stores/memory_store"
+require_relative "stores/redis_store"
+require_relative "stores/postgres_store"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      # Single source of truth for selecting a short-term store backend.
+      # Shared by Checkpoint, SessionLifecycle and WorkingMemory.
+      def self.build(store_type = nil)
+        case (store_type || Llmemory.configuration.short_term_store).to_sym
+        when :memory then MemoryStore.new
+        when :redis then RedisStore.new
+        when :postgres then PostgresStore.new
+        when :active_record, :activerecord
+          require_relative "stores/active_record_store"
+          ActiveRecordStore.new
+        else
+          MemoryStore.new
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/tokenizer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Llmemory
+  # Shared word tokenizer for keyword search and lexical scoring (BM25, MMR).
+  # Centralizes the tokenization regex that was duplicated across the codebase.
+  module Tokenizer
+    module_function
+
+    WORD = /\b[a-z0-9]{2,}\b/
+
+    def tokenize(text)
+      text.to_s.downcase.scan(WORD)
+    end
+
+    # Lexical match used by storage-level keyword search. A query is split into
+    # tokens and matched as an OR of per-token substrings, so multi-word queries
+    # work (a single contiguous substring of the whole query is no longer
+    # required) while single-term/partial matches are preserved. An empty query
+    # (no tokens) matches everything, keeping prior "return all" behavior.
+    def matches?(text, query)
+      tokens = tokenize(query)
+      return true if tokens.empty?
+      haystack = text.to_s.downcase
+      tokens.any? { |t| haystack.include?(t) }
+    end
+  end
+end

data/lib/llmemory/vector_store/active_record_store.rb

@@ -7,9 +7,10 @@ module Llmemory
     # Persists embeddings in llmemory_embeddings (pgvector).
     # Use when long_term_store is :active_record so hybrid search finds persisted embeddings.
     class ActiveRecordStore < Base
-      def initialize(embedding_provider: nil)
+      def initialize(embedding_provider: nil, source_type: "edge")
         self.class.load_model!
         @embedding_provider = embedding_provider
+        @source_type = source_type.to_s
       end
 
       def self.load_model!
@@ -29,7 +30,7 @@ module Llmemory
         text_content = (metadata || {}).dig("text") || (metadata || {}).dig(:text)
         rec = Llmemory::VectorStore::ActiveRecordEmbedding.find_or_initialize_by(
           user_id: user_id.to_s,
-          source_type: "edge",
+          source_type: @source_type,
           source_id: id.to_s
         )
         rec.embedding = embedding.to_a.map(&:to_f)
@@ -46,7 +47,7 @@ module Llmemory
         sanitized_vec = vec.map { |v| v.finite? ? v : 0.0 }
         vector_literal = "[#{sanitized_vec.join(',')}]"
         # pgvector cosine distance <=> (0 = same, 2 = opposite); score = 1 - distance for similarity
-        scope = Llmemory::VectorStore::ActiveRecordEmbedding.where(user_id: user_id.to_s)
+        scope = Llmemory::VectorStore::ActiveRecordEmbedding.where(user_id: user_id.to_s, source_type: @source_type)
         rows = scope.select(
           Llmemory::VectorStore::ActiveRecordEmbedding.arel_table[Arel.star],
           Arel.sql("(embedding <=> '#{vector_literal}'::vector) AS distance")

data/lib/llmemory/vector_store.rb

@@ -6,5 +6,19 @@ require_relative "vector_store/memory_store"
 
 module Llmemory
   module VectorStore
+    # Builds a vector store wired to OpenAI embeddings, selecting the backend
+    # from config (:active_record persists in llmemory_embeddings; otherwise
+    # in-process). `source_type` namespaces persisted embeddings so different
+    # memory types (edges, episodes, skills) never collide in the shared table.
+    def self.build(source_type: "edge")
+      embeddings = OpenAIEmbeddings.new
+      store_type = (Llmemory.configuration.long_term_store || :memory).to_s.to_sym
+      if store_type == :active_record || store_type == :activerecord
+        require_relative "vector_store/active_record_store"
+        ActiveRecordStore.new(embedding_provider: embeddings, source_type: source_type)
+      else
+        MemoryStore.new(embedding_provider: embeddings)
+      end
+    end
   end
 end

data/lib/llmemory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Llmemory
-  VERSION = "0.1.17"
+  VERSION = "0.2.1"
 end

data/lib/llmemory/working_memory.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "short_term/stores"
+
+module Llmemory
+  # CoALA's "working memory": a structured, symbolic scratch space that persists
+  # across LLM calls within a session — distinct from the raw message buffer
+  # (Checkpoint). It is the central hub an agent reads from and writes to while
+  # reasoning (goals, current task, retrieved context, intermediate reasoning,
+  # last observation, free-form scratchpad), plus arbitrary custom slots.
+  #
+  # Backed by the same pluggable short-term stores as Checkpoint, but under a
+  # namespaced session key so working-memory slots never collide with messages.
+  class WorkingMemory
+    DEFAULT_SESSION_ID = "default"
+    SESSION_SUFFIX = ":working_memory"
+    SLOTS = %i[goals current_task retrieved_context scratchpad last_observation intermediate_reasoning].freeze
+
+    attr_reader :user_id, :session_id
+
+    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, store: nil)
+      @user_id = user_id
+      @session_id = session_id
+      @store_key = "#{session_id}#{SESSION_SUFFIX}"
+      @store = store || ShortTerm::Stores.build
+    end
+
+    SLOTS.each do |slot|
+      define_method(slot) { read[slot] }
+      define_method("#{slot}=") { |value| set(slot, value) }
+    end
+
+    # Read/write an arbitrary slot (typed or custom).
+    def get(slot)
+      read[slot.to_sym]
+    end
+
+    def set(slot, value)
+      state = read
+      state[slot.to_sym] = value
+      persist(state)
+      value
+    end
+
+    # Bulk update in a single write.
+    def update(**slots)
+      state = read
+      slots.each { |k, v| state[k.to_sym] = v }
+      persist(state)
+      state
+    end
+
+    # Slots set by the caller beyond the predefined typed ones.
+    def custom_slots
+      read.reject { |k, _| SLOTS.include?(k) }
+    end
+
+    def to_h
+      read
+    end
+
+    def clear!
+      @store.delete(@user_id, @store_key)
+      true
+    end
+
+    private
+
+    def read
+      state = @store.load(@user_id, @store_key)
+      return {} unless state.is_a?(Hash)
+      symbolize(state)
+    end
+
+    def persist(state)
+      @store.save(@user_id, @store_key, state)
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end