llmemory 0.2.11 → 0.3.0

data/lib/llmemory/zero_mem/graph_retriever.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class GraphRetriever
+      MAX_NODES = 200
+
+      def initialize(storage, entity_index: nil, embedding_provider: nil, config: Llmemory.configuration)
+        @storage = storage
+        @entity_index = entity_index || EntityIndex.new(storage)
+        @embedding_provider = embedding_provider
+        @config = config
+        @pagerank = PageRank.new(gamma: config.zero_mem_pagerank_damping)
+      end
+
+      def retrieve(user_id:, query:, profile:, top_k:)
+        warnings = []
+        degraded = []
+        query_entities = @entity_index.extract_entities(query)
+        degraded << :ner if query_entities.empty?
+
+        seeds = match_entities(user_id, query, query_entities, degraded: degraded)
+        return empty_result(degraded, warnings) if seeds.empty?
+
+        trace_ids = seeds.flat_map { |key| @storage.trace_ids_for_entity_key(user_id, key) }.uniq
+        trace_ids = trace_ids.first(MAX_NODES)
+        warnings << :pagerank_truncated if trace_ids.size >= MAX_NODES
+
+        graph, reset = build_graph(user_id, trace_ids, seeds)
+        ranks = @pagerank.run(graph, reset)
+        trace_scores = ranks.select { |node, _| node.start_with?("tr:") }
+                            .transform_keys { |k| k.sub("tr:", "") }
+        trace_ids.each { |tid| trace_scores[tid] ||= 0.5 }
+        trace_scores = trace_scores.sort_by { |_, score| -score }
+
+        traces = trace_scores.first(top_k).map do |trace_id, score|
+          t = @storage.get_trace(user_id, trace_id)
+          next unless t
+
+          { trace: t, score: score }
+        end.compact
+
+        {
+          traces: traces.map { |h| h[:trace] },
+          trace_scores: trace_scores.to_h,
+          degraded: degraded.uniq,
+          warnings: warnings
+        }
+      end
+
+      private
+
+      def empty_result(degraded, warnings)
+        { traces: [], trace_scores: {}, degraded: degraded.uniq, warnings: warnings }
+      end
+
+      def match_entities(user_id, query, query_entities, degraded:)
+        keys = query_entities.map { |e| e[:normalized] }.compact
+        tokens = Llmemory::Tokenizer.tokenize(query)
+        keys = expand_entity_keys(user_id, keys) if keys.any?
+        if keys.empty?
+          keys = @storage.all_entity_keys(user_id).select do |key|
+            tokens.any? { |t| key.include?(t) || t.include?(key) }
+          end
+        end
+        degraded << :dense if @embedding_provider.nil?
+        keys.select { |k| @storage.entity_exists?(user_id, k) }
+      end
+
+      def expand_entity_keys(user_id, keys)
+        stored = @storage.all_entity_keys(user_id)
+        keys.flat_map do |k|
+          next [] if k.to_s.length < 2
+
+          stored.select { |s| s == k || s.include?(k) || k.include?(s) }
+        end.uniq
+      end
+
+      def build_graph(user_id, trace_ids, seed_keys)
+        graph = {}
+        reset = {}
+
+        trace_ids.each do |tid|
+          node = "tr:#{tid}"
+          neighbors = ["tr:#{tid}"]
+          @storage.entity_keys_for_trace(user_id, tid).each do |key|
+            ent_node = "ent:#{key}"
+            graph[ent_node] ||= []
+            graph[ent_node] << node
+            graph[node] ||= []
+            graph[node] << ent_node
+            neighbors << ent_node
+            reset[ent_node] = 1.0 if seed_keys.include?(key)
+          end
+          prev, nxt = @storage.adjacent_traces(user_id, tid)
+          [prev, nxt].compact.each do |other|
+            graph[node] ||= []
+            graph[node] << "tr:#{other}"
+          end
+          graph[node] = (graph[node] || neighbors).uniq
+        end
+
+        [graph, reset]
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/hierarchy_builder.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class HierarchyBuilder
+      def initialize(storage, config: Llmemory.configuration)
+        @storage = storage
+        @config = config
+      end
+
+      def index_trace(trace, index_version:)
+        affected = 0
+        affected += write_turn_unit(trace, index_version)
+        affected += update_tail_windows(trace, index_version)
+        affected += update_episode(trace, index_version)
+        affected
+      end
+
+      private
+
+      def window_size
+        @config.zero_mem_window_size.to_i.positive? ? @config.zero_mem_window_size.to_i : 8
+      end
+
+      def window_overlap
+        ov = @config.zero_mem_window_overlap.to_i
+        ov = 2 if ov.negative?
+        [ov, window_size - 1].min
+      end
+
+      def episode_gap_seconds
+        gap = @config.zero_mem_episode_gap_seconds.to_i
+        gap.positive? ? gap : 86_400
+      end
+
+      def write_turn_unit(trace, index_version)
+        unit = TraceUnit.build(
+          id: "turn_#{trace.id}",
+          user_id: trace.user_id,
+          kind: :turn,
+          session_id: trace.session_id,
+          boundary_id: trace.boundary_id,
+          start_sequence: trace.sequence,
+          end_sequence: trace.sequence,
+          occurred_from: trace.occurred_at,
+          occurred_to: trace.occurred_at,
+          member_trace_ids: [trace.id],
+          index_version: index_version
+        )
+        @storage.write_unit(unit)
+        1
+      end
+
+      def update_tail_windows(trace, index_version)
+        size = window_size
+        seq = trace.sequence
+        start_seq = [1, seq - size + 1].max
+        traces = @storage.list_traces(trace.user_id, session_id: trace.session_id).select do |t|
+          t.sequence >= start_seq && t.sequence <= seq
+        end
+        return 0 if traces.empty?
+
+        unit = TraceUnit.build(
+          id: "window_#{trace.session_id}_#{traces.first.sequence}_#{traces.last.sequence}",
+          user_id: trace.user_id,
+          kind: :window,
+          session_id: trace.session_id,
+          boundary_id: trace.boundary_id,
+          start_sequence: traces.first.sequence,
+          end_sequence: traces.last.sequence,
+          occurred_from: traces.first.occurred_at,
+          occurred_to: traces.last.occurred_at,
+          member_trace_ids: traces.map(&:id),
+          index_version: index_version
+        )
+        @storage.write_unit(unit)
+        1
+      end
+
+      def update_episode(trace, index_version)
+        key = trace.boundary_id || trace.session_id
+        open_episode = @storage.open_episode(trace.user_id, key)
+        gap = episode_gap_seconds
+
+        if open_episode
+          last_at = open_episode.occurred_to
+          if (trace.occurred_at - last_at).to_f > gap
+            @storage.close_episode(open_episode.id)
+            open_episode = nil
+          end
+        end
+
+        if open_episode
+          ids = (open_episode.member_trace_ids + [trace.id]).uniq
+          traces = ids.map { |id| @storage.get_trace(trace.user_id, id) }.compact
+          updated = open_episode.with(
+            end_sequence: trace.sequence,
+            occurred_to: trace.occurred_at,
+            member_trace_ids: ids,
+            index_version: index_version
+          )
+          @storage.write_unit(updated)
+        else
+          unit = TraceUnit.build(
+            user_id: trace.user_id,
+            kind: :episode,
+            session_id: trace.session_id,
+            boundary_id: trace.boundary_id,
+            start_sequence: trace.sequence,
+            end_sequence: trace.sequence,
+            occurred_from: trace.occurred_at,
+            occurred_to: trace.occurred_at,
+            member_trace_ids: [trace.id],
+            index_version: index_version
+          )
+          @storage.write_unit(unit)
+          @storage.set_open_episode(trace.user_id, key, unit.id)
+        end
+        1
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/hierarchy_retriever.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "../retrieval/bm25_scorer"
+
+module Llmemory
+  module ZeroMem
+    class HierarchyRetriever
+      def initialize(storage, config: Llmemory.configuration)
+        @storage = storage
+        @config = config
+        @bm25 = Retrieval::Bm25Scorer.new
+      end
+
+      def retrieve(user_id:, query:, profile:, top_k:)
+        k = top_k || @config.zero_mem_top_k
+        episodes = filtered_episodes(user_id, profile)
+        ranked_episodes = rank_units(query, profile, episodes)
+        top_episodes = ranked_episodes.first([k, ranked_episodes.size].min)
+
+        windows = top_episodes.flat_map do |ep|
+          @storage.list_units(user_id, kind: :window, session_id: ep.session_id).select do |w|
+            (w.member_trace_ids - ep.member_trace_ids).empty? || (w.member_trace_ids & ep.member_trace_ids).any?
+          end
+        end
+        windows = @storage.list_units(user_id, kind: :window) if windows.empty?
+        ranked_windows = rank_units(query, profile, windows.uniq { |u| u.id })
+        top_windows = ranked_windows.first([k, ranked_windows.size].min)
+
+        turns = top_windows.flat_map do |win|
+          @storage.list_units(user_id, kind: :turn, session_id: win.session_id).select do |t|
+            t.start_sequence >= win.start_sequence && t.end_sequence <= win.end_sequence
+          end
+        end
+        turns = @storage.list_units(user_id, kind: :turn) if turns.empty?
+        ranked_turns = rank_units(query, profile, turns.uniq { |u| u.id })
+        top_turns = ranked_turns.first([k, ranked_turns.size].min)
+
+        trace_ids = top_turns.flat_map(&:member_trace_ids)
+        trace_ids = expand_local_neighbors(user_id, trace_ids, top_turns)
+        traces = trace_ids.map { |id| @storage.get_trace(user_id, id) }.compact
+
+        {
+          traces: traces,
+          degraded: [:dense],
+          stage_scores: {
+            episodes: ranked_episodes.first(3).map { |u| score_unit(query, profile, u) },
+            windows: ranked_windows.first(3).map { |u| score_unit(query, profile, u) },
+            turns: ranked_turns.first(3).map { |u| score_unit(query, profile, u) }
+          }
+        }
+      end
+
+      private
+
+      def filtered_episodes(user_id, profile)
+        units = @storage.list_units(user_id, kind: :episode)
+        boundary = profile.boundary
+        return units unless boundary
+
+        units.select do |u|
+          ok = true
+          ok &&= (u.session_id == boundary[:session_id]) if boundary[:session_id]
+          ok &&= (u.boundary_id == boundary[:boundary_id]) if boundary[:boundary_id]
+          ok
+        end
+      end
+
+      def rank_units(query, profile, units)
+        docs = units.map do |u|
+          { id: u.id, text: unit_text(u), unit: u }
+        end
+        scored = @bm25.score_documents(query, docs)
+        scored.sort_by { |d| -combined_score(query, profile, d) }
+              .map { |d| d[:unit] }
+      end
+
+      def combined_score(query, profile, doc)
+        unit = doc[:unit]
+        bm25 = doc[:normalized_bm25].to_f
+        phrase = phrase_boost(profile, doc[:text])
+        subject = subject_boost(profile, doc[:text])
+        temporal = temporal_boost(profile, unit)
+        boundary = profile.boundary ? 0.1 : 0.0
+        answer = 0.05
+        bm25 + phrase + subject + temporal + boundary + answer
+      end
+
+      def score_unit(query, profile, unit)
+        doc = @bm25.score_documents(query, [{ id: unit.id, text: unit_text(unit), unit: unit }]).first
+        combined_score(query, profile, doc)
+      end
+
+      def unit_text(unit)
+        unit.member_trace_ids.map do |tid|
+          @storage.get_trace(unit.user_id, tid)&.content
+        end.compact.join(" ")
+      end
+
+      def phrase_boost(profile, text)
+        down = text.downcase
+        profile.quoted_phrases.count { |p| down.include?(p.downcase) } * 0.2
+      end
+
+      def subject_boost(profile, text)
+        down = text.downcase
+        profile.subject_entities.count { |e| down.include?(e.downcase) } * 0.15
+      end
+
+      def temporal_boost(profile, unit)
+        return 0.0 unless profile.freshness_requirement
+
+        age = Time.now - unit.occurred_to
+        1.0 / (1.0 + (age / 86_400.0))
+      end
+
+      def expand_local_neighbors(user_id, trace_ids, turn_units)
+        span = @config.zero_mem_local_span.to_i
+        span = 2 if span <= 0
+        sessions = turn_units.map(&:session_id).uniq
+        all_traces = sessions.flat_map { |sid| @storage.list_traces(user_id, session_id: sid) }
+        by_seq = all_traces.each_with_object({}) { |t, acc| acc[t.sequence] = t }
+        expanded = trace_ids.dup
+        turn_units.each do |tu|
+          seq = tu.start_sequence
+          ((seq - span)..(seq + span)).each do |s|
+            expanded << by_seq[s].id if by_seq[s]
+          end
+        end
+        expanded.uniq
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/indexer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    # Index watermark + hierarchical units + entity graph (ZM2/ZM3).
+    class Indexer
+      def initialize(storage, mode: nil, builder: nil, entity_index: nil, embedding_provider: nil)
+        @storage = storage
+        @mode = (mode || Llmemory.configuration.zero_mem_index_mode).to_sym
+        @builder = builder || HierarchyBuilder.new(storage)
+        @entity_index = entity_index || EntityIndex.new(storage)
+        @embedding_provider = embedding_provider
+      end
+
+      def after_trace_write(trace:, state_link: false)
+        wm = @storage.get_watermark(trace.user_id, trace.session_id)
+        next_version = wm[:index_version].to_i + 1
+        affected_units = @builder.index_trace(trace, index_version: next_version)
+        entity_stats = @entity_index.index_trace(trace)
+        encoder_stats = index_embedding(trace)
+
+        @storage.set_watermark(
+          trace.user_id,
+          trace.session_id,
+          last_sequence: trace.sequence,
+          index_version: next_version
+        )
+
+        {
+          index_mode: @mode,
+          index_lag: @mode == :deferred,
+          affected_units: affected_units,
+          affected_entities: entity_stats[:affected_entities],
+          cache_invalidations: entity_stats[:cache_invalidations],
+          maintenance_fanout: (state_link ? 2 : 1) + affected_units + entity_stats[:affected_entities],
+          encoder_calls: encoder_stats[:encoder_calls],
+          encoder_duration_ms: encoder_stats[:encoder_duration_ms]
+        }
+      end
+
+      private
+
+      def index_embedding(trace)
+        provider = @embedding_provider || configured_embedding_provider
+        return { encoder_calls: 0, encoder_duration_ms: 0.0 } unless provider
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        vector = provider.embed_one(trace.content)
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+        @storage.store_turn_embedding(
+          trace.user_id,
+          trace.id,
+          vector,
+          model: provider.model,
+          dimensions: provider.dimensions
+        )
+        Llmemory::Instrumentation.instrument(
+          :encoder_embed,
+          user_id: trace.user_id,
+          trace_id: trace.id,
+          model: provider.model,
+          dimensions: provider.dimensions,
+          duration_ms: elapsed
+        )
+        { encoder_calls: 1, encoder_duration_ms: elapsed }
+      end
+
+      def configured_embedding_provider
+        Llmemory.configuration.zero_mem_embedding_provider
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/mode.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    module Mode
+      MODES = %i[classic zero_mem hybrid].freeze
+
+      module_function
+
+      def valid?(mode)
+        MODES.include?(mode.to_sym)
+      end
+
+      def normalize(mode)
+        sym = (mode || :classic).to_sym
+        raise Llmemory::ConfigurationError, "invalid memory_mode: #{mode.inspect}" unless valid?(sym)
+
+        sym
+      end
+
+      def zero_mem_enabled?(mode)
+        %i[zero_mem hybrid].include?(normalize(mode))
+      end
+
+      def zero_mem_strict?(mode)
+        normalize(mode) == :zero_mem
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/pagerank.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class PageRank
+      def initialize(gamma: 0.6, max_iterations: 30, tolerance: 1e-6)
+        @gamma = gamma.to_f
+        @max_iterations = max_iterations
+        @tolerance = tolerance
+      end
+
+      # graph: { node_id => [neighbor_ids] }, reset: { node_id => weight }
+      def run(graph, reset)
+        nodes = (graph.keys + reset.keys).uniq
+        return {} if nodes.empty?
+
+        out_degree = graph.transform_values { |nbs| [nbs.size, 1].max }
+        rank = nodes.to_h { |n| [n, 1.0 / nodes.size] }
+        reset_total = reset.values.sum
+        reset = reset.transform_values { |w| reset_total.zero? ? 0.0 : w / reset_total }
+
+        @max_iterations.times do
+          next_rank = nodes.to_h { |n| [n, 0.0] }
+          graph.each do |node, neighbors|
+            share = rank[node] / out_degree[node]
+            neighbors.each do |nb|
+              next_rank[nb] ||= 0.0
+              next_rank[nb] += @gamma * share
+            end
+          end
+          nodes.each do |n|
+            next_rank[n] += (1.0 - @gamma) * reset.fetch(n, 0.0)
+          end
+          delta = nodes.sum { |n| (next_rank[n] - rank[n]).abs }
+          rank = next_rank
+          break if delta < @tolerance
+        end
+        rank
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/query_profile.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class QueryProfile
+      ANSWER_TYPES = %i[person place datetime number duration boolean list free_text].freeze
+      WORKLOADS = %i[local_fact cross_session temporal current_state multi_hop procedural].freeze
+
+      attr_reader :subject_entities, :keywords, :quoted_phrases, :answer_type, :temporal_cues,
+                  :aggregation_cues, :boundary, :workload_class, :freshness_requirement,
+                  :expected_evidence_count, :language, :rule_ids
+
+      def initialize(subject_entities:, keywords:, quoted_phrases:, answer_type:, temporal_cues:,
+                     aggregation_cues:, boundary:, workload_class:, freshness_requirement:,
+                     expected_evidence_count:, language:, rule_ids:)
+        @subject_entities = subject_entities
+        @keywords = keywords
+        @quoted_phrases = quoted_phrases
+        @answer_type = answer_type
+        @temporal_cues = temporal_cues
+        @aggregation_cues = aggregation_cues
+        @boundary = boundary
+        @workload_class = workload_class
+        @freshness_requirement = freshness_requirement
+        @expected_evidence_count = expected_evidence_count
+        @language = language
+        @rule_ids = rule_ids
+      end
+
+      def to_h
+        {
+          subject_entities: subject_entities,
+          keywords: keywords,
+          quoted_phrases: quoted_phrases,
+          answer_type: answer_type,
+          temporal_cues: temporal_cues,
+          aggregation_cues: aggregation_cues,
+          boundary: boundary,
+          workload_class: workload_class,
+          freshness_requirement: freshness_requirement,
+          expected_evidence_count: expected_evidence_count,
+          language: language,
+          rule_ids: rule_ids
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/query_profiler.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class QueryProfiler
+      TEMPORAL_EN = /\b(before|after|first|last|when|timeline|january|february|march|april|may|june|july|august|september|october|november|december|booking|remind)\b/i
+      TEMPORAL_ES = /\b(antes|después|primero|último|ultimo|cuándo|cuando|hora|enero|febrero|marzo|abril|mayo|junio|julio|agosto|septiembre|octubre|noviembre|diciembre|reserva|recuerda)\b/i
+      CURRENT_EN = /\b(now|today|current|currently|what is)\b/i
+      CURRENT_ES = /\b(ahora|actual|hoy|cuál es|cual es)\b/i
+      MULTI_EN = /\b(between|compared to|relationship|and .+ and)\b/i
+      MULTI_ES = /\b(relación|relacion|entre|comparado)\b/i
+      PROCEDURAL = /\b(export|file|balance|informe|report|saldo)\b/i
+
+      def profile(query, boundary: nil, language: nil)
+        text = query.to_s.strip
+        lang = language || detect_language(text)
+        rule_ids = []
+        quoted = text.scan(/"([^"]+)"/).flatten
+        keywords = Llmemory::Tokenizer.tokenize(text)
+        entities = extract_entities(text, lang)
+
+        temporal = temporal_cues(text, lang)
+        rule_ids << "temporal_cues" unless temporal.empty?
+
+        workload = infer_workload(text, lang, entities, temporal, rule_ids)
+        answer_type = infer_answer_type(text, lang, rule_ids)
+        freshness = workload == :current_state || workload == :temporal
+
+        boundary_h = normalize_boundary(boundary)
+        rule_ids << "boundary_explicit" if boundary_h
+
+        QueryProfile.new(
+          subject_entities: entities,
+          keywords: keywords,
+          quoted_phrases: quoted,
+          answer_type: answer_type,
+          temporal_cues: temporal,
+          aggregation_cues: aggregation_cues(text),
+          boundary: boundary_h,
+          workload_class: workload,
+          freshness_requirement: freshness,
+          expected_evidence_count: expected_count(workload, aggregation_cues(text)),
+          language: lang,
+          rule_ids: rule_ids.uniq
+        )
+      end
+
+      private
+
+      def detect_language(text)
+        text.match?(/[¿¡áéíóúñÁÉÍÓÚÑ]/) || text.match?(TEMPORAL_ES) ? :es : :en
+      end
+
+      def extract_entities(text, _lang)
+        text.scan(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b/).uniq.first(5)
+      end
+
+      def temporal_cues(text, lang)
+        cues = []
+        cues.concat(text.scan(lang == :es ? TEMPORAL_ES : TEMPORAL_EN).flatten)
+        cues.concat(text.scan(/\b\d{1,2}:\d{2}\b/))
+        cues.concat(text.scan(/\b\d{4}-\d{2}-\d{2}\b/))
+        cues.map(&:to_s).uniq
+      end
+
+      def aggregation_cues(text)
+        text.scan(/\b(all|every|list|cuántos|cuantos|how many)\b/i).flatten.uniq
+      end
+
+      def infer_workload(text, lang, entities, temporal, rule_ids)
+        if text.match?(PROCEDURAL)
+          rule_ids << "procedural_cue"
+          return :procedural
+        end
+        if entities.size >= 2 || text.match?(lang == :es ? MULTI_ES : MULTI_EN)
+          rule_ids << "multi_entity"
+          return :multi_hop
+        end
+        if text.match?(lang == :es ? CURRENT_ES : CURRENT_EN)
+          rule_ids << "current_state_cue"
+          return :current_state
+        end
+        if temporal.any?
+          rule_ids << "temporal_workload"
+          return :temporal
+        end
+        if text.match?(/\b(session|sesión|sesion|conversation|earlier)\b/i)
+          rule_ids << "cross_session_cue"
+          return :cross_session
+        end
+        :local_fact
+      end
+
+      def infer_answer_type(text, lang, rule_ids)
+        down = text.downcase
+        if down.match?(/\b(when|hora|time|fecha|date)\b/)
+          rule_ids << "answer_datetime"
+          return :datetime
+        end
+        if down.match?(/\b(how many|cuánt|cuant|number|número|numero)\b/)
+          rule_ids << "answer_number"
+          return :number
+        end
+        if down.match?(/\b(where|dónde|donde|place|address|dirección|direccion)\b/)
+          rule_ids << "answer_place"
+          return :place
+        end
+        if down.match?(/\b(yes|no|true|false|sí|si)\b/)
+          rule_ids << "answer_boolean"
+          return :boolean
+        end
+        if down.match?(/\b(list|which files|qué archivos|que archivos)\b/)
+          rule_ids << "answer_list"
+          return :list
+        end
+        :free_text
+      end
+
+      def expected_count(workload, aggregation_cues = [])
+        return [3, Llmemory.configuration.zero_mem_max_top_k].min if aggregation_cues.any?
+
+        case workload
+        when :multi_hop then 3
+        when :procedural then 2
+        when :temporal then 2
+        else 1
+        end
+      end
+
+      def normalize_boundary(boundary)
+        return nil if boundary.nil?
+
+        b = boundary.is_a?(Hash) ? boundary.transform_keys(&:to_sym) : { session_id: boundary }
+        b.compact
+      end
+    end
+  end
+end