llmemory 0.1.1

data/lib/llmemory/maintenance/consolidator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Llmemory
+  module Maintenance
+    class Consolidator
+      def initialize(storage)
+        @storage = storage
+      end
+
+      def run_nightly(user_id)
+        recent = @storage.get_items_since(user_id, hours: 24)
+        duplicates = find_duplicates(recent)
+
+        duplicates.each do |group|
+          merged = merge_items(group)
+          ids = group.map { |i| i[:id] }
+          @storage.replace_items(user_id, ids, merged)
+        end
+
+        true
+      end
+
+      private
+
+      def find_duplicates(items)
+        groups = []
+        seen = {}
+        items.each do |item|
+          key = normalize_content(item[:content].to_s)
+          next if key.empty?
+          seen[key] ||= []
+          seen[key] << item
+        end
+        seen.each_value { |v| groups << v if v.size > 1 }
+        groups
+      end
+
+      def normalize_content(content)
+        content.to_s.downcase.gsub(/\s+/, " ").strip[0..200]
+      end
+
+      def merge_items(group)
+        contents = group.map { |i| i[:content].to_s }.uniq
+        {
+          id: "merged_#{SecureRandom.hex(4)}",
+          category: group.first[:category],
+          content: contents.join("; "),
+          source_resource_id: group.first[:source_resource_id]
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance/reindexer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Maintenance
+    class Reindexer
+      ARCHIVE_AFTER_DAYS = 180
+
+      def initialize(storage)
+        @storage = storage
+      end
+
+      def run_monthly(user_id)
+        items = @storage.get_all_items(user_id)
+        resources = @storage.get_all_resources(user_id)
+        cutoff = Time.now - (ARCHIVE_AFTER_DAYS * 86400)
+
+        old_item_ids = items.select { |i| i[:created_at] < cutoff }.map { |i| i[:id] }
+        old_resource_ids = resources.select { |r| r[:created_at] < cutoff }.map { |r| r[:id] }
+
+        @storage.archive_items(user_id, old_item_ids) if old_item_ids.any?
+        @storage.archive_resources(user_id, old_resource_ids) if old_resource_ids.any?
+
+        true
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance/runner.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "consolidator"
+require_relative "summarizer"
+require_relative "reindexer"
+
+module Llmemory
+  module Maintenance
+    class Runner
+      class << self
+        def run_nightly(user_id, storage: nil)
+          storage ||= default_storage(user_id)
+          Consolidator.new(storage).run_nightly(user_id)
+        end
+
+        def run_weekly(user_id, storage: nil)
+          storage ||= default_storage(user_id)
+          Summarizer.new(storage).run_weekly(user_id)
+        end
+
+        def run_monthly(user_id, storage: nil)
+          storage ||= default_storage(user_id)
+          Reindexer.new(storage).run_monthly(user_id)
+        end
+
+        private
+
+        def default_storage(user_id)
+          Llmemory::LongTerm::FileBased::Storages.build
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance/summarizer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Maintenance
+    class Summarizer
+      def initialize(storage, llm: nil)
+        @storage = storage
+        @llm = llm || Llmemory::LLM.client
+      end
+
+      def run_weekly(user_id, prune_after_days: nil)
+        prune_after_days ||= Llmemory.configuration.prune_after_days
+        old_items = @storage.get_items_older_than(user_id, days: 30)
+        categories = group_by_category(old_items)
+
+        categories.each do |category, items|
+          next if items.empty?
+          summary = create_summary(items)
+          existing = @storage.load_category(user_id, category)
+          updated = existing.to_s.empty? ? summary : "#{existing}\n\n## Archived summary\n#{summary}"
+          @storage.save_category(user_id, category, updated)
+          @storage.archive_items(user_id, items.map { |i| i[:id] })
+        end
+
+        prune_stale_items(user_id, prune_after_days)
+        true
+      end
+
+      private
+
+      def group_by_category(items)
+        items.group_by { |i| i[:category] }
+      end
+
+      def create_summary(items)
+        bullet_points = items.map { |i| "- #{i[:content]}" }.join("\n")
+        return bullet_points if bullet_points.length < 500
+        prompt = <<~PROMPT
+          Summarize these memory items into a short markdown paragraph (max 200 words).
+          Items:
+          #{bullet_points}
+          Return only the summary.
+        PROMPT
+        @llm.invoke(prompt.strip).to_s
+      rescue Llmemory::LLMError
+        bullet_points[0..500]
+      end
+
+      def prune_stale_items(user_id, days)
+        old = @storage.get_items_older_than(user_id, days: days)
+        return if old.empty?
+        ids = old.map { |i| i[:id] }
+        @storage.archive_items(user_id, ids)
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "maintenance/runner"
+
+module Llmemory
+  module Maintenance
+  end
+end

data/lib/llmemory/memory.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "short_term/checkpoint"
+require_relative "long_term/file_based"
+require_relative "retrieval/engine"
+
+module Llmemory
+  class Memory
+    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)
+      @user_id = user_id
+      @session_id = session_id
+      @checkpoint = checkpoint || ShortTerm::Checkpoint.new(user_id: user_id, session_id: session_id)
+      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)
+    end
+
+    def add_message(role:, content:)
+      msgs = messages
+      msgs << { role: role.to_sym, content: content.to_s }
+      save_state(messages: msgs)
+      true
+    end
+
+    def messages
+      state = @checkpoint.restore_state
+      return [] unless state.is_a?(Hash)
+      list = state[STATE_KEY_MESSAGES] || state[STATE_KEY_MESSAGES.to_s]
+      list.is_a?(Array) ? list.dup : []
+    end
+
+    def retrieve(query, max_tokens: nil)
+      short_context = format_short_term_context(messages)
+      long_context = @retrieval_engine.retrieve_for_inference(query, user_id: @user_id, max_tokens: max_tokens)
+      combine_contexts(short_context, long_context)
+    end
+
+    def consolidate!
+      msgs = messages
+      return true if msgs.empty?
+      conversation_text = msgs.map { |m| "#{m[:role]}: #{m[:content]}" }.join("\n")
+      @long_term.memorize(conversation_text)
+      true
+    end
+
+    def clear_session!
+      @checkpoint.clear_state
+      true
+    end
+
+    def user_id
+      @user_id
+    end
+
+    private
+
+    def build_long_term(long_term_type)
+      case long_term_type.to_s.to_sym
+      when :graph_based
+        LongTerm::GraphBased::Memory.new(
+          user_id: @user_id,
+          storage: LongTerm::GraphBased::Storages.build
+        )
+      else
+        LongTerm::FileBased::Memory.new(user_id: @user_id, storage: LongTerm::FileBased::Storages.build)
+      end
+    end
+
+    def save_state(messages:)
+      @checkpoint.save_state(STATE_KEY_MESSAGES => messages)
+    end
+
+    def format_short_term_context(msgs)
+      return "" if msgs.empty?
+      lines = ["=== RECENT CONVERSATION ===", ""]
+      msgs.each do |m|
+        role = m[:role] || m["role"]
+        content = m[:content] || m["content"]
+        lines << "#{role}: #{content}"
+      end
+      lines << ""
+      lines << "=== END RECENT CONVERSATION ==="
+      lines.join("\n")
+    end
+
+    def combine_contexts(short_context, long_context)
+      parts = []
+      parts << short_context if short_context.to_s.strip.length.positive?
+      parts << long_context.to_s.strip if long_context.to_s.strip.length.positive?
+      parts.join("\n\n")
+    end
+  end
+end

data/lib/llmemory/retrieval/context_assembler.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Retrieval
+    class ContextAssembler
+      def initialize(max_tokens: nil)
+        @max_tokens = max_tokens || Llmemory.configuration.max_retrieval_tokens
+      end
+
+      def assemble(ranked_memories, max_tokens: nil)
+        max_tokens ||= @max_tokens
+        selected = []
+        token_count = 0
+
+        ranked_memories.each do |memory|
+          text = memory[:text] || memory["text"] || ""
+          memory_tokens = count_tokens(text)
+          break if token_count + memory_tokens > max_tokens
+
+          selected << {
+            text: text,
+            timestamp: memory[:timestamp] || memory["timestamp"],
+            confidence: memory[:temporal_score] || memory[:score] || memory["score"]
+          }
+          token_count += memory_tokens
+        end
+
+        format_context(selected)
+      end
+
+      def count_tokens(text)
+        (text.to_s.length / 4.0).ceil
+      end
+
+      private
+
+      def format_context(memories)
+        lines = ["=== RELEVANT MEMORIES ===", ""]
+        memories.each do |mem|
+          ts = mem[:timestamp]
+          ts_str = ts.respond_to?(:iso8601) ? ts.iso8601 : ts.to_s
+          conf = mem[:confidence]
+          conf_str = conf.is_a?(Numeric) ? format("%.2f", conf) : conf.to_s
+          lines << "[#{ts_str}] (confidence: #{conf_str})"
+          lines << mem[:text].to_s
+          lines << ""
+        end
+        lines << "=== END MEMORIES ==="
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/llmemory/retrieval/engine.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "temporal_ranker"
+require_relative "context_assembler"
+
+module Llmemory
+  module Retrieval
+    class Engine
+      RELEVANCE_THRESHOLD = 0.7
+
+      def initialize(memory, llm: nil)
+        @memory = memory
+        @llm = llm || Llmemory::LLM.client
+        @ranker = TemporalRanker.new
+        @assembler = ContextAssembler.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)
+        candidates = fetch_candidates(search_query, user_id)
+
+        relevant = filter_by_relevance(candidates, user_message)
+        ranked = @ranker.rank(relevant)
+        @assembler.assemble(ranked, max_tokens: max_tokens)
+      end
+
+      private
+
+      def generate_query(user_message)
+        return user_message.to_s if user_message.to_s.length <= 100
+        prompt = <<~PROMPT
+          Summarize this user message into a short search query (one sentence, under 15 words) to find relevant memories.
+          Message: #{user_message}
+          Return only the search query.
+        PROMPT
+        @llm.invoke(prompt.strip).to_s.strip
+      rescue Llmemory::LLMError
+        user_message.to_s[0..200]
+      end
+
+      def fetch_candidates(search_query, user_id)
+        return [] unless @memory.respond_to?(:search_candidates)
+
+        raw = @memory.search_candidates(search_query, user_id: user_id, top_k: 20)
+        raw.map do |c|
+          {
+            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
+          }
+        end
+      end
+
+      def parse_timestamp(ts)
+        return ts if ts.is_a?(Time)
+        return Time.parse(ts.to_s) if ts
+        Time.now
+      end
+
+      def filter_by_relevance(candidates, user_message)
+        return candidates if candidates.size <= 5
+        user_lower = user_message.to_s.downcase
+        candidates.select do |c|
+          text = (c[:text] || c["text"]).to_s.downcase
+          score = (c[:score] || c["score"] || 1.0).to_f
+          next true if score >= RELEVANCE_THRESHOLD
+          next true if user_lower.split.any? { |w| w.length > 3 && text.include?(w) }
+          score >= 0.5
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/retrieval/temporal_ranker.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Retrieval
+    class TemporalRanker
+      def initialize(half_life_days: nil)
+        @half_life_days = half_life_days || Llmemory.configuration.time_decay_half_life_days
+      end
+
+      def rank(candidates, now: Time.now)
+        candidates.map do |c|
+          score = (c[:score] || c["score"] || 1.0).to_f
+          timestamp = c[:timestamp] || c["timestamp"]
+          timestamp = Time.parse(timestamp.to_s) if timestamp.is_a?(String)
+          age_days = timestamp ? (now - timestamp).to_i / 86400 : 0
+          time_decay = 1.0 / (1.0 + (age_days.to_f / @half_life_days))
+          final_score = score * time_decay
+          c.merge(score: score, temporal_score: final_score, timestamp: timestamp)
+        end.sort_by { |c| -(c[:temporal_score] || 0) }
+      end
+    end
+  end
+end

data/lib/llmemory/retrieval.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "retrieval/temporal_ranker"
+require_relative "retrieval/context_assembler"
+require_relative "retrieval/engine"
+
+module Llmemory
+  module Retrieval
+  end
+end

data/lib/llmemory/short_term/checkpoint.rb

@@ -0,0 +1,47 @@
+# 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
+    class Checkpoint
+      DEFAULT_SESSION_ID = "default"
+
+      def initialize(user_id:, session_id: DEFAULT_SESSION_ID, store: nil)
+        @user_id = user_id
+        @session_id = session_id
+        @store = store || build_store
+      end
+
+      def save_state(state)
+        @store.save(@user_id, @session_id, state)
+      end
+
+      def restore_state
+        @store.load(@user_id, @session_id)
+      end
+
+      def clear_state
+        @store.delete(@user_id, @session_id)
+      end
+
+      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
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/stores/active_record_checkpoint.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Model for short-term checkpoint (ActiveRecordStore). Table: llmemory_checkpoints.
+# Create with: rails g llmemory:install && rails db:migrate
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class ActiveRecordCheckpoint < ::ActiveRecord::Base
+        self.table_name = "llmemory_checkpoints"
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/stores/active_record_store.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class ActiveRecordStore < Base
+        def initialize
+          self.class.load_model!
+        end
+
+        def self.load_model!
+          return if @model_loaded
+          require "active_record"
+          require_relative "active_record_checkpoint"
+          @model_loaded = true
+        end
+
+        def save(user_id, session_id, state)
+          record = Llmemory::ShortTerm::Stores::ActiveRecordCheckpoint.find_or_initialize_by(
+            user_id: user_id,
+            session_id: session_id
+          )
+          record.state = state
+          record.updated_at = Time.current
+          record.save!
+          true
+        end
+
+        def load(user_id, session_id)
+          record = Llmemory::ShortTerm::Stores::ActiveRecordCheckpoint.find_by(
+            user_id: user_id,
+            session_id: session_id
+          )
+          return nil unless record
+          raw = record.state
+          raw.is_a?(Hash) ? raw.transform_keys(&:to_sym) : deserialize(raw)
+        end
+
+        def delete(user_id, session_id)
+          Llmemory::ShortTerm::Stores::ActiveRecordCheckpoint.where(
+            user_id: user_id,
+            session_id: session_id
+          ).destroy_all
+          true
+        end
+
+        private
+
+        def deserialize(data)
+          return data if data.is_a?(Hash)
+          JSON.parse(data.to_s, symbolize_names: true)
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/stores/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class Base
+        def save(user_id, session_id, state)
+          raise NotImplementedError, "#{self.class}#save must be implemented"
+        end
+
+        def load(user_id, session_id)
+          raise NotImplementedError, "#{self.class}#load must be implemented"
+        end
+
+        def delete(user_id, session_id)
+          raise NotImplementedError, "#{self.class}#delete must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/stores/memory_store.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class MemoryStore < Base
+        def initialize
+          @store = {}
+        end
+
+        def save(user_id, session_id, state)
+          key = key_for(user_id, session_id)
+          @store[key] = { state: state, updated_at: Time.now }
+          true
+        end
+
+        def load(user_id, session_id)
+          key = key_for(user_id, session_id)
+          @store.dig(key, :state)
+        end
+
+        def delete(user_id, session_id)
+          @store.delete(key_for(user_id, session_id))
+          true
+        end
+
+        private
+
+        def key_for(user_id, session_id)
+          "#{user_id}:#{session_id}"
+        end
+      end
+    end
+  end
+end