llmemory 0.2.10 → 0.3.0

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

data/lib/llmemory/zero_mem/repair.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class Repair
+      def initialize(storage:)
+        @storage = storage
+      end
+
+      # Reconcile watermark with persisted traces and checkpoint message counts (ZM1).
+      def run!(user_id:, session_id:, checkpoint_messages:)
+        traces = @storage.list_traces(user_id, session_id: session_id)
+        last_sequence = traces.map(&:sequence).max.to_i
+        wm = @storage.get_watermark(user_id, session_id)
+        @storage.set_watermark(
+          user_id,
+          session_id,
+          last_sequence: last_sequence,
+          index_version: [wm[:index_version].to_i, last_sequence].max
+        )
+
+        {
+          trace_count: traces.size,
+          checkpoint_message_count: Array(checkpoint_messages).size,
+          last_sequence: last_sequence,
+          index_version: [wm[:index_version].to_i, last_sequence].max
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/router.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class Router
+      RELATIONAL_WORKLOADS = %i[multi_hop].freeze
+      LOCAL_WORKLOADS = %i[temporal procedural cross_session local_fact].freeze
+
+      def route(profile, hierarchy_scores:, graph_scores:, config: Llmemory.configuration)
+        weights, route, tie_break = route_for_workload(profile, config)
+        if tie_break
+          weights = resolve_tie(weights, hierarchy_scores, graph_scores, profile)
+        end
+
+        {
+          route: route,
+          weights: weights,
+          rho: weights[:graph],
+          tie_break: tie_break
+        }
+      end
+
+      private
+
+      def route_for_workload(profile, config)
+        workload = profile.workload_class
+        if RELATIONAL_WORKLOADS.include?(workload) || profile.aggregation_cues.any?
+          return [relational_weights(config), :relational, false]
+        end
+        if LOCAL_WORKLOADS.include?(workload)
+          return [local_weights(config), :local, false]
+        end
+        if workload == :current_state
+          base = profile.subject_entities.size >= 2 ? relational_weights(config) : local_weights(config)
+          return [base, :current_state, profile.subject_entities.size < 2]
+        end
+
+        [local_weights(config), :local, true]
+      end
+
+      def relational_weights(config)
+        rho = config.zero_mem_graph_weight || 0.6
+        { graph: rho.to_f, hierarchy: 1.0 - rho.to_f }
+      end
+
+      def local_weights(_config)
+        { graph: 0.4, hierarchy: 0.6 }
+      end
+
+      def resolve_tie(default_weights, hierarchy_scores, graph_scores, profile)
+        h = anchor_confidence(hierarchy_scores, profile)
+        g = anchor_confidence(graph_scores, profile)
+        if g > h
+          relational_weights(Llmemory.configuration)
+        elsif h > g
+          local_weights(Llmemory.configuration)
+        else
+          default_weights
+        end
+      end
+
+      def anchor_confidence(scores, profile)
+        return 0.0 if scores.nil? || scores.empty?
+
+        scores.values.sum.to_f / scores.size
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/sidecar_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "faraday"
+
+module Llmemory
+  module ZeroMem
+    class SidecarClient
+      MAX_TEXT_BYTES = 32_768
+
+      def initialize(base_url:, timeout: 5, breaker: nil)
+        @base_url = base_url.to_s.sub(%r{/\z}, "")
+        @timeout = timeout.to_f
+        @breaker = breaker || CircuitBreaker.new
+        validate_host!
+      end
+
+      def get_json(path)
+        raise StoreError, "sidecar circuit open" unless @breaker.allow_request?
+
+        response = connection.get(path)
+        unless response.success?
+          @breaker.record_failure
+          raise StoreError, "sidecar HTTP error: #{response.status}"
+        end
+        @breaker.record_success
+        JSON.parse(response.body)
+      rescue Faraday::Error
+        @breaker.record_failure
+        raise StoreError, "sidecar request failed"
+      end
+
+      def post_json(path, body)
+        raise StoreError, "sidecar circuit open" unless @breaker.allow_request?
+
+        text = body[:text].to_s
+        if text.bytesize > MAX_TEXT_BYTES
+          raise StoreError, "sidecar payload exceeds max text bytes (#{MAX_TEXT_BYTES})"
+        end
+
+        response = connection.post(path) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = body.to_json
+        end
+        unless response.success?
+          @breaker.record_failure
+          raise StoreError, "sidecar HTTP error: #{response.status}"
+        end
+
+        @breaker.record_success
+        JSON.parse(response.body)
+      rescue Faraday::Error
+        @breaker.record_failure
+        raise StoreError, "sidecar request failed"
+      end
+
+      def degraded?
+        @breaker.open?
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: @base_url, request: { timeout: @timeout, open_timeout: @timeout }) do |f|
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def validate_host!
+        return unless Llmemory.configuration.zero_mem_require_local_encoders
+
+        uri = URI.parse(@base_url)
+        host = uri.host.to_s
+        allowed = %w[127.0.0.1 localhost ::1]
+        return if allowed.include?(host)
+
+        raise ConfigurationError, "zero_mem sidecar host must be loopback when require_local_encoders is enabled"
+      end
+    end
+  end
+end