llmemory 0.2.10 → 0.3.0

data/lib/llmemory/zero_mem/backfill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Llmemory
+  module ZeroMem
+    class Backfill
+      WARNING = "Backfill only covers messages still present in the checkpoint; " \
+                "text removed by prior LLM compaction cannot be reconstructed."
+
+      def initialize(storage:, indexer: nil)
+        @storage = storage
+        @indexer = indexer || Indexer.new(storage)
+      end
+
+      def run!(user_id:, session_id:, messages:, id_prefix: "backfill")
+        created = []
+        Array(messages).each_with_index do |msg, idx|
+          role = msg[:role] || msg["role"]
+          content = msg[:content] || msg["content"]
+          next if content.to_s.empty?
+
+          sequence = @storage.next_sequence(user_id, session_id)
+          trace = Trace.build(
+            user_id: user_id,
+            session_id: session_id,
+            role: role,
+            content: content,
+            sequence: sequence,
+            idempotency_key: "#{id_prefix}-#{idx}-#{Digest::SHA256.hexdigest(content.to_s)[0, 12]}"
+          )
+          next if @storage.find_by_idempotency_key(user_id, trace.idempotency_key)
+
+          @storage.write_trace(trace)
+          @indexer.after_trace_write(trace: trace)
+          created << trace.id
+        end
+
+        { created_trace_ids: created, warning: WARNING }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/budget_assembler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class BudgetAssembler
+      RESERVE_TOKENS = 64
+
+      def assemble(evidence, max_tokens:, local_reserve: RESERVE_TOKENS, atomic_groups: nil)
+        budget = max_tokens&.to_i
+        return evidence if budget.nil? || budget <= 0
+
+        reserve = [local_reserve, budget / 4].min
+        remaining = budget - reserve
+        selected = []
+        used_ids = {}
+
+        groups = build_atomic_groups(evidence, atomic_groups)
+        ungrouped = evidence.reject { |ev| groups.any? { |g| g.include?(ev.trace_id) } }
+
+        groups.each do |group|
+          members = group.map { |id| evidence.find { |ev| ev.trace_id == id } }.compact
+          cost = members.sum { |ev| token_cost(ev) }
+          next if cost > remaining
+
+          members.each do |ev|
+            selected << ev
+            used_ids[ev.trace_id] = true
+          end
+          remaining -= cost
+        end
+
+        ungrouped.each do |ev|
+          next if used_ids[ev.trace_id]
+
+          cost = token_cost(ev)
+          next if cost > remaining && !selected.empty?
+
+          if cost <= remaining
+            selected << ev
+            remaining -= cost
+          end
+        end
+
+        selected
+      end
+
+      def build_atomic_groups(evidence, explicit_groups)
+        ids = evidence.map(&:trace_id)
+        Array(explicit_groups).map do |group|
+          Array(group).map(&:to_s).select { |id| ids.include?(id) }
+        end.reject(&:empty?)
+      end
+
+      private
+
+      def token_cost(evidence)
+        line = "[#{evidence.trace_id}] #{evidence.role}: #{evidence.content}"
+        (Llmemory::Tokenizer.tokenize(line).size + 4)
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/circuit_breaker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class CircuitBreaker
+      def initialize(failure_threshold: 3, cool_down_seconds: 30)
+        @failure_threshold = failure_threshold.to_i
+        @cool_down_seconds = cool_down_seconds.to_i
+        @failures = 0
+        @opened_at = nil
+      end
+
+      def allow_request?
+        return true if @opened_at.nil?
+        return false if (Time.now - @opened_at) < @cool_down_seconds
+
+        @opened_at = nil
+        @failures = 0
+        true
+      end
+
+      def record_success
+        @failures = 0
+        @opened_at = nil
+      end
+
+      def record_failure
+        @failures += 1
+        @opened_at = Time.now if @failures >= @failure_threshold
+      end
+
+      def open?
+        !allow_request?
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/embedding_provider.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    module EmbeddingProvider
+      def embed(texts)
+        raise NotImplementedError
+      end
+
+      def model
+        raise NotImplementedError
+      end
+
+      def dimensions
+        raise NotImplementedError
+      end
+
+      def local?
+        false
+      end
+
+      def last_usage
+        Llmemory::LLM::Usage.zero
+      end
+
+      def embed_one(text)
+        embed([text]).first
+      end
+    end
+
+    # Deterministic vectors for tests (no HTTP).
+    class FakeEmbeddingProvider
+      include EmbeddingProvider
+
+      attr_reader :calls
+
+      def initialize(dimensions: 8, model: "fake-embed")
+        @dimensions = dimensions
+        @model = model
+        @calls = 0
+      end
+
+      def embed(texts)
+        @calls += 1
+        Array(texts).map { |text| vector_for(text) }
+      end
+
+      def model
+        @model
+      end
+
+      def dimensions
+        @dimensions
+      end
+
+      def local?
+        true
+      end
+
+      private
+
+      def vector_for(text)
+        seed = Digest::SHA256.hexdigest(text.to_s)
+        @dimensions.times.map do |i|
+          byte = seed.bytes[i % seed.bytes.length] || 0
+          (byte / 255.0)
+        end
+      end
+    end
+  end
+end
+
+require "digest"

data/lib/llmemory/zero_mem/engine.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require_relative "../retrieval/bm25_scorer"
+
+module Llmemory
+  module ZeroMem
+    class Engine
+      def initialize(trace_store:, user_id:, config: nil, profiler: nil, retriever: nil,
+                     graph_retriever: nil, calibrator: nil, assembler: nil, entity_index: nil,
+                     embedding_provider: nil, router: nil, fusion: nil, closure: nil, **options)
+        if options.key?(:llm) || options.key?("llm")
+          raise ArgumentError, "ZeroMem::Engine does not accept an llm client"
+        end
+
+        @storage = trace_store
+        @user_id = user_id
+        @config = config || Llmemory.configuration
+        @profiler = profiler || QueryProfiler.new
+        @retriever = retriever || HierarchyRetriever.new(@storage, config: @config)
+        @entity_index = entity_index || EntityIndex.new(@storage)
+        @embedding_provider = embedding_provider
+        @graph_retriever = graph_retriever || GraphRetriever.new(
+          @storage,
+          entity_index: @entity_index,
+          embedding_provider: @embedding_provider,
+          config: @config
+        )
+        @calibrator = calibrator || EvidenceCalibrator.new(@storage)
+        @assembler = assembler || BudgetAssembler.new
+        @router = router || Router.new
+        @fusion = fusion || EvidenceFusion.new
+        @closure = closure || EvidenceClosure.new(@storage, config: @config)
+        @bm25 = Retrieval::Bm25Scorer.new
+      end
+
+      def retrieve_evidence(query, top_k: nil, max_tokens: nil, boundary: nil, explain: false,
+                            current_trace_id: nil, skip_closure: false, skip_calibration: false,
+                            fusion_weights: nil)
+        effective_k = effective_top_k(top_k, nil)
+        metrics = { llm_calls: 0, encoder_calls: 0, encoder_duration_ms: 0.0, stages: {} }
+
+        profile = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_profile, user_id: @user_id, query_chars: query.to_s.length) do
+          profile = @profiler.profile(query, boundary: boundary)
+        end
+        effective_k = effective_top_k(top_k, profile)
+
+        retrieval = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_hierarchy_retrieve, user_id: @user_id, workload: profile.workload_class) do
+          retrieval = @retriever.retrieve(user_id: @user_id, query: query, profile: profile, top_k: effective_k)
+        end
+
+        graph = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_graph_retrieve, user_id: @user_id) do
+          graph = @graph_retriever.retrieve(user_id: @user_id, query: query, profile: profile, top_k: effective_k)
+        end
+
+        degraded = (retrieval[:degraded] + graph[:degraded]).uniq
+        degraded << :dense unless @embedding_provider
+        degraded.uniq!
+
+        hierarchy_scores = hierarchy_trace_scores(query, retrieval[:traces])
+        graph_scores = graph[:trace_scores] || {}
+        routing = @router.route(profile, hierarchy_scores: hierarchy_scores, graph_scores: graph_scores, config: @config)
+        weights = fusion_weights || routing[:weights]
+
+        fused = @fusion.fuse(graph_scores: graph_scores, hierarchy_scores: hierarchy_scores, weights: weights)
+        seed_rows = fused.first(effective_k)
+        seed_ids = seed_rows.map { |r| r[:trace_id] }
+
+        closure_result = if skip_closure
+                           { seed_trace_ids: seed_ids, closure_trace_ids: [], bridges: [], atomic_groups: [] }
+                         else
+                           Llmemory::Instrumentation.instrument(:zero_mem_closure, user_id: @user_id, seeds: seed_ids.size) do
+                             @closure.expand(
+                               user_id: @user_id,
+                               profile: profile,
+                               seed_trace_ids: seed_ids,
+                               fused_ranking: fused
+                             )
+                           end
+                         end
+
+        ordered_ids = (seed_ids + closure_result[:closure_trace_ids]).uniq
+        traces = ordered_ids.map { |id| @storage.get_trace(@user_id, id) }.compact
+
+        calibration = if skip_calibration
+                        { traces: traces, excluded: [], conflict_trace_ids: [], seed_ids: seed_ids,
+                          closure_ids: closure_result[:closure_trace_ids] }
+                      else
+                        Llmemory::Instrumentation.instrument(:zero_mem_calibrate, user_id: @user_id, trace_count: traces.size) do
+                          @calibrator.calibrate(
+                            user_id: @user_id,
+                            traces: traces,
+                            profile: profile,
+                            current_trace_id: current_trace_id,
+                            fusion_rows: fused,
+                            seed_ids: seed_ids,
+                            closure_ids: closure_result[:closure_trace_ids]
+                          )
+                        end
+                      end
+
+        fusion_by_id = fused.each_with_object({}) { |row, acc| acc[row[:trace_id].to_s] = row }
+        conflict_ids = calibration[:conflict_trace_ids].to_h { |id| [id.to_s, true] }
+
+        evidence = calibration[:traces].map do |trace|
+          row = fusion_by_id[trace.id]
+          score = row ? row[:final] : 0.5
+          Evidence.new(
+            trace_id: trace.id,
+            content: trace.content,
+            role: trace.role,
+            session_id: trace.session_id,
+            occurred_at: trace.occurred_at,
+            confidence: score.clamp(0.0, 1.0),
+            score: score.clamp(0.0, 1.0),
+            sources: row ? row[:sources] : [],
+            conflict: conflict_ids[trace.id] == true,
+            seed: seed_ids.include?(trace.id),
+            closure: closure_result[:closure_trace_ids].include?(trace.id),
+            content_sha256: trace.content_sha256
+          )
+        end
+
+        seed_evidence = evidence.select(&:seed)
+        closure_evidence = evidence.select(&:closure)
+
+        packed = @assembler.assemble(
+          evidence,
+          max_tokens: max_tokens,
+          atomic_groups: closure_result[:atomic_groups]
+        )
+
+        explain_payload = if explain
+                              build_explain(
+                                profile: profile,
+                                routing: routing,
+                                weights: weights,
+                                effective_k: effective_k,
+                                graph: graph,
+                                retrieval: retrieval,
+                                fused: fused,
+                                calibration: calibration,
+                                closure_result: closure_result,
+                                degraded: degraded,
+                                warnings: graph[:warnings]
+                              )
+                            end
+
+        result = EvidenceSet.new(
+          route: routing[:route],
+          profile: profile,
+          evidence: packed,
+          seed_evidence: seed_evidence.select { |ev| packed.any? { |p| p.trace_id == ev.trace_id } },
+          closure_evidence: closure_evidence.select { |ev| packed.any? { |p| p.trace_id == ev.trace_id } },
+          metrics: metrics.merge(
+            degraded: degraded,
+            seed_recall: seed_evidence.map(&:trace_id),
+            closure_recall: (seed_evidence + closure_evidence).map(&:trace_id).uniq
+          ),
+          explain: explain_payload,
+          degraded: degraded,
+          relational_trace_scores: graph_scores,
+          hierarchy_traces: retrieval[:traces],
+          relational_traces: graph[:traces],
+          warnings: graph[:warnings]
+        )
+
+        Llmemory::Instrumentation.instrument(
+          :zero_mem_retrieve,
+          user_id: @user_id,
+          evidence_count: packed.size,
+          degraded: degraded,
+          seed_count: seed_evidence.size,
+          closure_count: closure_evidence.size
+        )
+
+        result
+      end
+
+      def to_context(query, **opts)
+        retrieve_evidence(query, **opts).to_context
+      end
+
+      private
+
+      def effective_top_k(explicit, profile)
+        base = explicit || @config.zero_mem_top_k
+        need = profile ? [base, profile.expected_evidence_count].max : base
+        [need, @config.zero_mem_max_top_k].min
+      end
+
+      def hierarchy_trace_scores(query, traces)
+        docs = traces.map { |t| { id: t.id, text: t.content } }
+        return {} if docs.empty?
+
+        @bm25.score_documents(query, docs).to_h { |d| [d[:id], d[:normalized_bm25].to_f] }
+      end
+
+      def build_explain(profile:, routing:, weights:, effective_k:, graph:, retrieval:, fused:,
+                        calibration:, closure_result:, degraded:, warnings:)
+        {
+          profile: profile.to_h,
+          route: routing[:route],
+          weights: weights,
+          thresholds: {
+            rho: routing[:rho],
+            gamma: @config.zero_mem_pagerank_damping,
+            top_k: effective_k
+          },
+          graph: {
+            seeds: graph[:trace_scores]&.keys&.first(5),
+            nodes_visited: graph[:traces]&.size,
+            truncated: warnings.include?(:pagerank_truncated),
+            boosts: []
+          },
+          hierarchy: {
+            episodes: retrieval[:stage_scores][:episodes],
+            windows: retrieval[:stage_scores][:windows],
+            turns: retrieval[:stage_scores][:turns]
+          },
+          fusion: {
+            per_trace: fused.first(effective_k).map do |row|
+              {
+                id: row[:trace_id],
+                graph: row[:graph],
+                hierarchy: row[:hierarchy],
+                final: row[:final],
+                sources: row[:sources]
+              }
+            end
+          },
+          included: calibration[:traces].map(&:id),
+          excluded: calibration[:excluded],
+          closure: {
+            seed_ids: closure_result[:seed_trace_ids],
+            closure_ids: closure_result[:closure_trace_ids],
+            bridges: closure_result[:bridges]
+          },
+          warnings: warnings,
+          degraded: degraded
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/entity.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Llmemory
+  module ZeroMem
+    class Entity
+      attr_reader :id, :user_id, :normalized_key, :display_name, :entity_type, :ambiguous
+
+      def self.build(user_id:, normalized_key:, display_name: nil, entity_type: :entity, id: nil, ambiguous: false)
+        new(
+          id: id || "ent_#{Digest::SHA256.hexdigest([user_id, normalized_key].join(':'))[0, 16]}",
+          user_id: user_id.to_s,
+          normalized_key: normalized_key.to_s,
+          display_name: display_name || normalized_key.to_s,
+          entity_type: entity_type.to_sym,
+          ambiguous: ambiguous
+        )
+      end
+
+      def initialize(id:, user_id:, normalized_key:, display_name:, entity_type:, ambiguous:)
+        @id = id
+        @user_id = user_id
+        @normalized_key = normalized_key
+        @display_name = display_name
+        @entity_type = entity_type
+        @ambiguous = ambiguous
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/entity_extractor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class EntityExtractor
+      def extract(_text)
+        raise NotImplementedError
+      end
+
+      def generative?
+        false
+      end
+
+      def name
+        self.class.name.split("::").last.downcase
+      end
+
+      def version
+        "1"
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/entity_index.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class EntityIndex
+      def initialize(storage, extractor: nil)
+        @storage = storage
+        @extractor = extractor || build_extractor
+      end
+
+      def extract_entities(text)
+        @extractor.extract(text)
+      end
+
+      def index_trace(trace)
+        entities_touched = 0
+        mentions = @extractor.extract(trace.content)
+        keys = []
+
+        mentions.each do |m|
+          entity = Entity.build(
+            user_id: trace.user_id,
+            normalized_key: m[:normalized],
+            display_name: m[:text]
+          )
+          @storage.upsert_entity(entity)
+          mention = EntityMention.build(
+            user_id: trace.user_id,
+            trace_id: trace.id,
+            entity_id: entity.id,
+            normalized_key: entity.normalized_key,
+            text: m[:text],
+            offset_start: m[:start],
+            offset_end: m[:end]
+          )
+          @storage.write_mention(mention)
+          keys << entity.normalized_key
+          entities_touched += 1
+        end
+
+        prev = @storage.previous_trace(trace.user_id, trace.session_id, trace.sequence)
+        if prev
+          @storage.link_adjacent_traces(trace.user_id, prev.id, trace.id)
+        end
+
+        {
+          affected_entities: entities_touched,
+          entity_keys: keys.uniq,
+          cache_invalidations: entities_touched
+        }
+      end
+
+      private
+
+      def build_extractor
+        case Llmemory.configuration.zero_mem_entity_extractor.to_sym
+        when :http
+          Extractors::Http.new(base_url: Llmemory.configuration.zero_mem_ner_http_url)
+        else
+          Extractors::Heuristic.new
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/entity_mention.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class EntityMention
+      attr_reader :id, :user_id, :trace_id, :entity_id, :normalized_key, :text, :offset_start, :offset_end
+
+      def self.build(user_id:, trace_id:, entity_id:, normalized_key:, text:, offset_start: 0, offset_end: nil, id: nil)
+        new(
+          id: id || "men_#{SecureRandom.hex(8)}",
+          user_id: user_id.to_s,
+          trace_id: trace_id.to_s,
+          entity_id: entity_id.to_s,
+          normalized_key: normalized_key.to_s,
+          text: text.to_s,
+          offset_start: offset_start.to_i,
+          offset_end: (offset_end || offset_start.to_i + text.to_s.length).to_i
+        )
+      end
+
+      def initialize(id:, user_id:, trace_id:, entity_id:, normalized_key:, text:, offset_start:, offset_end:)
+        @id = id
+        @user_id = user_id
+        @trace_id = trace_id
+        @entity_id = entity_id
+        @normalized_key = normalized_key
+        @text = text
+        @offset_start = offset_start
+        @offset_end = offset_end
+      end
+    end
+  end
+end
+
+require "securerandom"

data/lib/llmemory/zero_mem/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    ValidationError = Class.new(Llmemory::Error)
+  end
+end

data/lib/llmemory/zero_mem/evidence.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class Evidence
+      attr_reader :trace_id, :content, :role, :session_id, :occurred_at, :confidence, :score,
+                  :sources, :conflict, :seed, :closure, :content_sha256
+
+      def initialize(trace_id:, content:, role:, session_id:, occurred_at:, confidence:, score:,
+                     sources: [], conflict: false, seed: true, closure: false, content_sha256: nil)
+        @trace_id = trace_id
+        @content = content
+        @role = role
+        @session_id = session_id
+        @occurred_at = occurred_at
+        @confidence = confidence.to_f
+        @score = score.to_f
+        @sources = Array(sources).map(&:to_sym).uniq
+        @conflict = !!conflict
+        @seed = !!seed
+        @closure = !!closure
+        @content_sha256 = content_sha256
+      end
+
+      def to_h
+        {
+          trace_id: trace_id,
+          content: content,
+          role: role,
+          session_id: session_id,
+          occurred_at: occurred_at.is_a?(Time) ? occurred_at.utc.iso8601(6) : occurred_at,
+          confidence: confidence,
+          score: score,
+          sources: sources,
+          conflict: conflict,
+          seed: seed,
+          closure: closure,
+          content_sha256: content_sha256
+        }
+      end
+    end
+  end
+end