phronomy 0.2.2 → 0.3.0

data/lib/phronomy/memory/compression/summary.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Compression
-      # Compaction strategy that summarizes old messages with an LLM.
-      #
-      # When the total estimated token count of the uncompacted message history
-      # exceeds +max_tokens+, all messages except the most recent +keep+ are
-      # summarized by an LLM. The original messages are preserved in Storage
-      # (via ConversationManager); this class only decides whether compaction is
-      # needed and produces the summary text.
-      #
-      # The #compress method now returns a Hash instead of a plain Array:
-      #   {
-      #     messages:   Array,            # context-ready message list
-      #     compaction: Hash | nil        # { start_seq:, end_seq:, summary_text: }
-      #                                   # nil when no compaction was performed
-      #   }
-      #
-      # ConversationManager uses the :compaction entry to persist the compaction
-      # record in Storage, ensuring originals are never discarded.
-      #
-      # @example
-      #   compressor = Phronomy::Memory::Compression::Summary.new(
-      #     max_tokens: 4000,
-      #     summarizer_model: "gpt-4o-mini"
-      #   )
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval,
-      #     compression: compressor
-      #   )
-      class Summary < Base
-        # @param max_tokens          [Integer]     token threshold above which old messages are compacted
-        # @param keep                [Integer]     number of recent messages to preserve verbatim
-        # @param summarizer_model    [String, nil] LLM model for summarization; nil uses global default
-        # @param summarizer_provider [Symbol, nil] LLM provider; required for unregistered models
-        def initialize(max_tokens: 4000, keep: 5, summarizer_model: nil, summarizer_provider: nil)
-          @max_tokens = max_tokens
-          @keep = keep
-          @summarizer_model = summarizer_model
-          @summarizer_provider = summarizer_provider
-        end
-
-        # Evaluate whether compaction is needed and produce a summary if so.
-        #
-        # +seq_offset+ is the seq number of messages[0] in the raw history.
-        # ConversationManager passes this so the compaction record can reference
-        # the correct seq range in Storage.
-        #
-        # @param thread_id  [String]
-        # @param messages   [Array]   uncompacted messages to consider
-        # @param seq_offset [Integer] seq number assigned to messages[0]
-        # @return [Hash] { messages: Array, compaction: Hash|nil }
-        #   compaction is { start_seq:, end_seq:, summary_text: } or nil
-        def compress(thread_id:, messages:, seq_offset: 0)
-          estimated = messages.sum { |m| Phronomy::Context::TokenEstimator.estimate(m.content.to_s) }
-
-          if estimated > @max_tokens && messages.length > @keep
-            compact(messages, seq_offset: seq_offset)
-          else
-            {messages: messages, compaction: nil}
-          end
-        rescue => e
-          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
-          {messages: messages, compaction: nil}
-        end
-
-        private
-
-        def compact(messages, seq_offset:)
-          old_count = messages.length - @keep
-          old_messages = messages[0, old_count]
-          recent_messages = messages[old_count..]
-
-          opts = {}
-          opts[:model] = @summarizer_model if @summarizer_model
-          opts[:provider] = @summarizer_provider if @summarizer_provider
-          opts[:assume_model_exists] = true if @summarizer_provider
-          chat = RubyLLM.chat(**opts)
-          summary_text = chat.ask(
-            "Please summarize the following conversation concisely:\n" +
-              old_messages.map { |m| "#{m.role}: #{m.content}" }.join("\n")
-          ).content
-
-          compaction_record = {
-            start_seq: seq_offset,
-            end_seq: seq_offset + old_count - 1,
-            summary_text: summary_text
-          }
-
-          {messages: [summary_message(summary_text)] + recent_messages, compaction: compaction_record}
-        end
-
-        def summary_message(text)
-          content = <<~CONTEXT.chomp
-            <context type="summary" source="memory" trusted="false">
-            #{text}
-            </context>
-          CONTEXT
-          RubyLLM::Message.new(role: :system, content: content)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/compression/tool_output_pruner.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Compression
-      # Compression strategy that truncates oversized tool-call result messages.
-      #
-      # Large tool outputs — such as a full web-page dump or a massive JSON
-      # response — can consume a significant fraction of the context window.
-      # This compressor truncates the content of any :tool message whose character
-      # count exceeds max_chars, appending a note that the output was truncated.
-      #
-      # Unlike Summary, this is a stateless compressor: it does not accumulate
-      # state across calls and requires no thread_id bookkeeping.
-      #
-      # @example
-      #   compressor = Phronomy::Memory::Compression::ToolOutputPruner.new(max_chars: 4000)
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval,
-      #     compression: compressor
-      #   )
-      class ToolOutputPruner < Base
-        TRUNCATION_NOTE = "\n[... output truncated ...]"
-
-        # Internal value object for cloned messages.
-        # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
-        ClonedMessage = Struct.new(:role, :content, :tool_calls, :model_id, keyword_init: true)
-        private_constant :ClonedMessage
-
-        # @param max_chars [Integer] maximum character length for tool-result content
-        def initialize(max_chars: 4000)
-          @max_chars = max_chars
-        end
-
-        # Truncate oversized :tool messages in-place (non-destructive — returns new array).
-        # Content pruning does not produce a compaction record; :compaction is always nil.
-        #
-        # @param thread_id  [String]  unused (stateless pruner)
-        # @param messages   [Array]
-        # @param seq_offset [Integer] unused
-        # @return [Hash] { messages: Array, compaction: nil }
-        def compress(thread_id:, messages:, seq_offset: 0)
-          pruned = messages.map do |msg|
-            next msg unless msg.role.to_sym == :tool
-            next msg if msg.content.to_s.length <= @max_chars
-
-            truncated = msg.content.to_s[0, @max_chars] + TRUNCATION_NOTE
-            clone_message(msg, truncated)
-          end
-          {messages: pruned, compaction: nil}
-        end
-
-        private
-
-        def clone_message(original, new_content)
-          ClonedMessage.new(
-            role: original.role,
-            content: new_content,
-            tool_calls: (original.tool_calls if original.respond_to?(:tool_calls)),
-            model_id: (original.model_id if original.respond_to?(:model_id))
-          )
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/compression.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # Compression is the reduction axis of conversation management.
-    # Implementations transform a message array into a smaller representation
-    # (e.g. LLM summary, tool-output truncation) before storage or retrieval.
-    module Compression
-    end
-  end
-end

data/lib/phronomy/memory/conversation_manager.rb

@@ -1,213 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # ConversationManager combines the three independent axes of conversation handling:
-    #   - Storage:     where messages are persisted (InMemory, ActiveRecord, ...)
-    #   - Retrieval:   which messages to select (Recent, Semantic, ...)
-    #   - Compression: how to reduce message size before storage (Summary, ToolOutputPruner, ...)
-    #
-    # This is the primary entry point for context region 4 (Conversation) in Agent::Base.
-    #
-    # === Original preservation policy
-    #
-    # All original messages are appended to Storage's raw history with a
-    # monotonically increasing seq number (0-based, per thread). Raw messages
-    # are never modified or deleted.
-    #
-    # When Compression::Summary performs a compaction, a compaction record
-    # { start_seq:, end_seq:, summary_text: } is saved in Storage alongside the
-    # raw messages. This allows callers to reconstruct the full history or audit
-    # which messages were summarised.
-    #
-    # On #load, the message list is reconstructed from raw history + compaction
-    # records: each compacted range is replaced by a single summary system message,
-    # and uncompacted messages are returned verbatim.
-    #
-    # @example Simple recency-based in-memory manager
-    #   manager = Phronomy::Memory::ConversationManager.new(
-    #     storage:   Phronomy::Memory::Storage::InMemory.new,
-    #     retrieval: Phronomy::Memory::Retrieval::Recent.new(k: 10)
-    #   )
-    #
-    # @example With LLM summary compaction
-    #   manager = Phronomy::Memory::ConversationManager.new(
-    #     storage:     Phronomy::Memory::Storage::InMemory.new,
-    #     retrieval:   Phronomy::Memory::Retrieval::Recent.new(k: 5),
-    #     compression: Phronomy::Memory::Compression::Summary.new(max_tokens: 4000)
-    #   )
-    class ConversationManager
-      # @param storage     [Memory::Storage::Base]     persistence backend (required)
-      # @param retrieval   [Memory::Retrieval::Base]   selection strategy (required)
-      # @param compression [Memory::Compression::Base, nil] optional compression strategy
-      # @param ttl         [Integer, nil] message time-to-live in seconds; messages older
-      #                    than this value are removed from storage on each {#load} call.
-      #                    +nil+ disables TTL (default).
-      def initialize(storage:, retrieval:, compression: nil, ttl: nil)
-        @storage = storage
-        @retrieval = retrieval
-        @compression = compression
-        @ttl = ttl
-      end
-
-      # Load conversation messages for a thread, applying retrieval selection.
-      #
-      # When a TTL is configured, raw messages older than the TTL are permanently
-      # removed from storage before reconstruction.
-      #
-      # Reconstructs the message list from raw history + compaction records:
-      #   - Each compacted range [start_seq..end_seq] is replaced by a summary
-      #     system message.
-      #   - Uncompacted messages are returned in original order.
-      #
-      # @param thread_id [String]
-      # @param query     [String, nil] current user input for query-aware retrieval
-      # @return [Array]
-      def load(thread_id:, query: nil)
-        @storage.purge_older_than(thread_id: thread_id, older_than: Time.now - @ttl) if @ttl
-        messages = reconstruct(thread_id)
-        @retrieval.select(messages, query: query, thread_id: thread_id)
-      end
-
-      # Persist new messages for a thread and optionally apply compression.
-      #
-      # New messages are determined by comparing the incoming array length with
-      # the existing raw history length (messages are always append-only).
-      # Only truly new messages (beyond raw.length) are appended to raw storage.
-      #
-      # When a compression strategy is configured, it is evaluated against the
-      # full set of uncompacted raw messages. If compaction fires, the resulting
-      # compaction record is saved in storage (originals are preserved).
-      #
-      # @param thread_id [String]
-      # @param messages  [Array] full conversation history up to this point
-      def save(thread_id:, messages:)
-        @storage.with_thread_lock(thread_id: thread_id) do
-          append_new_messages(thread_id: thread_id, messages: messages)
-          compress_and_save(thread_id: thread_id, messages: messages)
-        end
-        @retrieval.index(thread_id: thread_id, messages: messages) if @retrieval.respond_to?(:index)
-      end
-
-      # Delete all messages (raw, compaction records, and legacy store) for a thread.
-      #
-      # @param thread_id [String]
-      def clear(thread_id:)
-        @storage.clear(thread_id: thread_id)
-        @retrieval.clear_index(thread_id: thread_id) if @retrieval.respond_to?(:clear_index)
-      end
-
-      # Permanently erase all stored data for a thread (right-to-erasure / purge).
-      # Delegates to the storage backend's {Storage::Base#purge} and also clears
-      # any retrieval index for the thread.
-      #
-      # @param thread_id [String]
-      def purge(thread_id:)
-        @storage.purge(thread_id: thread_id)
-        @retrieval.clear_index(thread_id: thread_id) if @retrieval.respond_to?(:clear_index)
-      end
-
-      # Record an application-driven compaction for a thread.
-      # Called by CompactionContext when the on_compact callback invokes ctx.compact.
-      #
-      # @param thread_id   [String]
-      # @param start_seq   [Integer] first seq number in the compacted range
-      # @param end_seq     [Integer] last seq number in the compacted range
-      # @param summary_text [String] replacement text for the compacted messages
-      def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-        @storage.save_compaction(
-          thread_id: thread_id,
-          start_seq: start_seq,
-          end_seq: end_seq,
-          summary_text: summary_text
-        )
-      end
-
-      private
-
-      # Append messages that are new since the last save to the raw history.
-      # Must be called while holding the per-thread lock (via Storage#with_thread_lock).
-      # Messages are append-only; existing raw entries are never modified.
-      #
-      # The next seq number is derived from Storage#next_seq, which owns the
-      # high-water-mark counter. This survives TTL purges because Storage tracks
-      # the HWM independently of the stored raw entries.
-      def append_new_messages(thread_id:, messages:)
-        next_seq = @storage.next_seq(thread_id: thread_id)
-        new_messages = messages[next_seq..]
-        @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq) if new_messages&.any?
-      end
-
-      # Apply the configured compression strategy and persist the result.
-      # When no strategy is configured, saves messages directly to the legacy store.
-      # When compression fires, also persists the compaction record.
-      # If the compression strategy raises (e.g. LLM timeout), we fall back to
-      # saving the messages without compaction so the conversation is never lost
-      # due to a transient summarization failure (Issue #58).
-      def compress_and_save(thread_id:, messages:)
-        unless @compression
-          @storage.save(thread_id: thread_id, messages: messages)
-          return
-        end
-
-        compactions = @storage.load_compactions(thread_id: thread_id)
-        uncompacted_start_seq = compactions.any? ? compactions.last[:end_seq] + 1 : 0
-        all_raw = @storage.load_raw(thread_id: thread_id)
-        uncompacted = all_raw.select { |r| r[:seq] >= uncompacted_start_seq }.map { |r| r[:message] }
-
-        result = begin
-          @compression.compress(
-            thread_id: thread_id,
-            messages: uncompacted,
-            seq_offset: uncompacted_start_seq
-          )
-        rescue => e
-          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
-          {messages: messages, compaction: nil}
-        end
-
-        if result[:compaction]
-          @storage.save_compaction(
-            thread_id: thread_id,
-            start_seq: result[:compaction][:start_seq],
-            end_seq: result[:compaction][:end_seq],
-            summary_text: result[:compaction][:summary_text]
-          )
-        end
-
-        # For non-Summary compressors (ToolOutputPruner), store the pruned
-        # version in the legacy store so legacy #load still works.
-        @storage.save(thread_id: thread_id, messages: result[:messages])
-      end
-
-      # Reconstruct context-ready messages from raw history + compaction records.
-      # When no compaction records exist (no Summary compaction has fired), we
-      # return the legacy store directly — this preserves the effect of content
-      # pruners like ToolOutputPruner, whose pruned messages are saved there.
-      # When compaction records exist, we rebuild the context from raw history:
-      # each compacted seq range is replaced by a single summary system message.
-      def reconstruct(thread_id)
-        compactions = @storage.load_compactions(thread_id: thread_id)
-        return @storage.load(thread_id: thread_id) if compactions.empty?
-
-        raw = @storage.load_raw(thread_id: thread_id)
-        last_compacted_seq = compactions.last[:end_seq]
-        summary_msgs = compactions.map { |c| summary_message(c[:summary_text]) }
-        uncompacted = raw.select { |r| r[:seq] > last_compacted_seq }.map { |r| r[:message] }
-        summary_msgs + uncompacted
-      end
-
-      # Immutable value object used as a summary placeholder in reconstructed context.
-      SummaryMessage = Data.define(:role, :content)
-
-      def summary_message(text)
-        content = <<~CONTEXT.chomp
-          <context type="summary" source="memory" trusted="false">
-          #{text}
-          </context>
-        CONTEXT
-        SummaryMessage.new(role: :system, content: content)
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval/base.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Abstract base class for conversation retrieval strategies.
-      #
-      # @abstract Subclass and implement #select.
-      class Base
-        # Select messages to inject into the context from a full chronological history.
-        #
-        # @param messages  [Array]        full history in chronological order
-        # @param query     [String, nil]  current user input for query-aware retrieval
-        # @param thread_id [String, nil]  active thread identifier for scoped retrieval
-        # @return [Array] subset of messages in chronological order
-        def select(messages, query: nil, thread_id: nil)
-          raise NotImplementedError, "#{self.class}#select is not implemented"
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval/composite.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that merges results from multiple child retrieval strategies.
-      #
-      # Each child is given a weight that controls what fraction of a token budget
-      # it should consume. Results are deduplicated (by role + content) and
-      # system messages are sorted to the front.
-      #
-      # @example
-      #   composite = Phronomy::Memory::Retrieval::Composite.new(
-      #     sources: [
-      #       { retrieval: Phronomy::Memory::Retrieval::Recent.new(k: 5),    weight: 0.4 },
-      #       { retrieval: Phronomy::Memory::Retrieval::Semantic.new(...),   weight: 0.6 }
-      #     ]
-      #   )
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage:   Phronomy::Memory::Storage::InMemory.new,
-      #     retrieval: composite
-      #   )
-      class Composite < Base
-        # @param sources [Array<Hash>] each entry: { retrieval:, weight: } (weight default 1.0)
-        def initialize(sources:)
-          @sources = sources.map { |s| {retrieval: s[:retrieval], weight: (s[:weight] || 1.0).to_f} }
-        end
-
-        # Merge results from all child retrievals, deduplicating by role+content.
-        # System messages are sorted to the front; others preserve insertion order.
-        #
-        # @param messages  [Array]        full chronological history
-        # @param query     [String, nil]  forwarded to each child retrieval
-        # @param thread_id [String, nil]  forwarded to each child retrieval
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          all_messages = []
-          seen = {}
-
-          @sources.each do |source|
-            source[:retrieval].select(messages, query: query, thread_id: thread_id).each do |msg|
-              key = "#{msg.role}:#{msg.content}"
-              next if seen[key]
-
-              seen[key] = true
-              all_messages << msg
-            end
-          end
-
-          systems = all_messages.select { |m| m.role.to_sym == :system }
-          others = all_messages.reject { |m| m.role.to_sym == :system }
-          systems + others
-        end
-
-        # Forward index calls to all child retrievals that support it.
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def index(thread_id:, messages:)
-          @sources.each do |source|
-            source[:retrieval].index(thread_id: thread_id, messages: messages) if source[:retrieval].respond_to?(:index)
-          end
-        end
-
-        # Forward clear_index to all child retrievals that support it.
-        #
-        # @param thread_id [String]
-        def clear_index(thread_id:)
-          @sources.each do |source|
-            source[:retrieval].clear_index(thread_id: thread_id) if source[:retrieval].respond_to?(:clear_index)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval/recent.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that returns the most recent k turns (k*2 messages).
-      #
-      # This is the simplest and most predictable strategy: older messages are
-      # discarded without compression.
-      #
-      # @example
-      #   retrieval = Phronomy::Memory::Retrieval::Recent.new(k: 10)
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval
-      #   )
-      class Recent < Base
-        # @param k [Integer] number of turns to retain (each turn = 1 user + 1 assistant message)
-        def initialize(k: 10)
-          @k = k
-        end
-
-        # Returns the last k*2 messages from the history.
-        #
-        # @param messages  [Array]        full chronological history
-        # @param query     [String, nil]  unused for recency-based retrieval
-        # @param thread_id [String, nil]  unused for recency-based retrieval
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          messages.last(@k * 2)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval/semantic.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that returns the k semantically closest messages to the query.
-      #
-      # Messages are indexed in a VectorStore on save. On retrieval, the query is
-      # embedded and the k nearest messages are returned. Falls back to the k most
-      # recent messages when no query is provided.
-      #
-      # @example
-      #   retrieval = Phronomy::Memory::Retrieval::Semantic.new(
-      #     embeddings: Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small"),
-      #     k: 10
-      #   )
-      class Semantic < Base
-        # @param store      [Phronomy::VectorStore::Base]  vector store (default InMemory)
-        # @param embeddings [Phronomy::Embeddings::Base]   embeddings adapter
-        # @param k          [Integer]                      number of messages to retrieve
-        # @param max_index_size [Integer, nil] maximum number of entries kept in the
-        #   local index. When nil, the index grows unboundedly. When exceeded, the
-        #   oldest entries (by insertion order) are evicted.
-        def initialize(embeddings:, store: nil, k: 10, max_index_size: nil)
-          @store = store || Phronomy::VectorStore::InMemory.new
-          @embeddings = embeddings
-          @k = k
-          @index = {}   # id => message  (insertion-ordered via Ruby Hash)
-          @counter = 0
-          @max_index_size = max_index_size
-          @actor = Phronomy::Actor.new
-          @indexed_object_ids = {}  # thread_id => { object_id => true }
-        end
-
-        # Index a new batch of messages so they are searchable on future #select calls.
-        # Called by ConversationManager#save.
-        #
-        # Messages are deduplicated by object identity: if a message object has already
-        # been indexed for the given thread_id, it is skipped (no duplicate embed call).
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def index(thread_id:, messages:)
-          messages.each do |msg|
-            # Fast path: skip already-indexed messages without calling embed.
-            already_indexed = @actor.call do
-              (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
-            end
-            next if already_indexed
-
-            embedding = @embeddings.embed(msg.content.to_s)
-            @actor.call do
-              # Re-check inside Actor to handle concurrent callers for the same thread.
-              indexed = (@indexed_object_ids[thread_id] ||= {})
-              next if indexed[msg.object_id]
-
-              id = "#{thread_id}:#{@counter}"
-              @counter += 1
-              @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
-              @index[id] = msg
-              indexed[msg.object_id] = true
-              evict_oldest! if @max_index_size && @index.size > @max_index_size
-            end
-          end
-        end
-
-        # Clear indexed messages for a thread.
-        #
-        # @param thread_id [String]
-        def clear_index(thread_id:)
-          @actor.call do
-            ids = @index.keys.select { |id| id.start_with?("#{thread_id}:") }
-            ids.each do |id|
-              @index.delete(id)
-              @store.remove(id: id)
-            end
-            @indexed_object_ids.delete(thread_id)
-          end
-        end
-
-        # Return semantically relevant messages, or recent messages when query is nil.
-        #
-        # @param messages   [Array]        full history (used as fallback when query is nil)
-        # @param query      [String, nil]  current user input for semantic search
-        # @param thread_id  [String, nil]  when provided, results are filtered to this thread
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          if query && !query.strip.empty?
-            query_embedding = @embeddings.embed(query)
-            results = @actor.call { @store.search(query_embedding: query_embedding, k: @k * 3) }
-            results
-              .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
-              .first(@k)
-              .map { |r| r[:metadata][:message] }
-          else
-            messages.last(@k)
-          end
-        end
-
-        private
-
-        # Evicts the oldest index entry to enforce max_index_size.
-        # Must be called inside the Actor.
-        def evict_oldest!
-          oldest_id = @index.keys.first
-          return unless oldest_id
-
-          @index.delete(oldest_id)
-          @store.remove(id: oldest_id)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # Retrieval is the selection axis of conversation management.
-    # Implementations decide which messages from a full history to return
-    # given a query and a maximum message count or token limit.
-    # Token budgeting is NOT their responsibility — that belongs to Context::Assembler.
-    module Retrieval
-    end
-  end
-end