phronomy 0.1.2 → 0.1.4

data/lib/phronomy/graph/compiled_graph.rb

@@ -169,7 +169,15 @@ module Phronomy
       def next_node(current, state)
         if (cond = @conditional_edges[current])
           result = cond[:condition].call(state)
-          return cond[:mapping] ? cond[:mapping][result] : result
+          if cond[:mapping]
+            unless cond[:mapping].key?(result)
+              raise ArgumentError,
+                "Conditional edge from #{current.inspect} returned #{result.inspect}, " \
+                "which is not present in the mapping (#{cond[:mapping].keys.inspect})"
+            end
+            return cond[:mapping][result]
+          end
+          return result
         end
 
         edges = @edges[current]

data/lib/phronomy/graph/parallel_node.rb

@@ -64,36 +64,47 @@ module Phronomy
       def call(state)
         threads = @branches.map { |branch| Thread.new { branch.call(state) } }
         deadline = @timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout) : nil
+        state_class = state.class
 
         if @on_error == :best_effort
-          gather_best_effort(threads, deadline)
+          gather_best_effort(threads, deadline, state_class)
         else
-          gather_raise(threads, deadline)
+          gather_raise(threads, deadline, state_class)
         end
       end
 
       private
 
       # Joins all threads, enforcing the deadline. Re-raises branch exceptions.
-      def gather_raise(threads, deadline)
+      def gather_raise(threads, deadline, state_class)
         if deadline
           threads.each do |t|
             remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
             next if t.join([remaining, 0].max)
 
             # Thread did not finish within the time limit.
-            threads.each(&:kill)
+            # Use Thread#raise instead of Thread#kill so that ensure blocks in
+            # branches (DB connection return, Mutex release, etc.) are executed.
+            timeout_error = Phronomy::Graph::TimeoutError.new(
+              "parallel branch timed out after #{@timeout}s"
+            )
+            threads.each { |thr| thr.raise(timeout_error) unless thr.stop? }
+            threads.each do |thr|
+              thr.join(0.1)
+            rescue
+              nil
+            end
             raise Phronomy::Graph::TimeoutError,
               "parallel branch timed out after #{@timeout}s"
           end
         end
 
         # All threads are done. Thread#value re-raises any stored exception.
-        merge_results(threads.map(&:value))
+        merge_results(threads.map(&:value), state_class)
       end
 
       # Joins all threads, collecting errors instead of re-raising them.
-      def gather_best_effort(threads, deadline)
+      def gather_best_effort(threads, deadline, state_class)
         errors = []
         results = threads.map do |t|
           if deadline
@@ -108,7 +119,15 @@ module Phronomy
               next nil
             end
             if joined.nil?
-              t.kill
+              timeout_error = Phronomy::Graph::TimeoutError.new(
+                "branch timed out after #{@timeout}s"
+              )
+              t.raise(timeout_error) unless t.stop?
+              begin
+                t.join(0.1)
+              rescue
+                nil
+              end
               errors << Phronomy::Graph::TimeoutError.new(
                 "branch timed out after #{@timeout}s"
               )
@@ -124,33 +143,49 @@ module Phronomy
           end
         end
 
-        merged = merge_results(results) || {}
+        merged = merge_results(results, state_class) || {}
         merged[:parallel_errors] = errors unless errors.empty?
         merged.empty? ? nil : merged
       end
 
       # Merges an Array of per-branch result Hashes (nils are skipped).
-      def merge_results(results)
+      # Field merge policy is determined from the State class field declarations:
+      #   :replace fields  — last-write-wins (rightmost branch wins)
+      #   :append  fields  — all Arrays are concatenated
+      #   :merge   fields  — all Hashes are deep-merged (rightmost wins on conflict)
+      # Unknown / undeclared fields fall back to type-based heuristics.
+      def merge_results(results, state_class = nil)
         merged = results.compact.each_with_object({}) do |result, acc|
           next unless result.is_a?(Hash)
 
           result.each do |key, val|
-            acc[key] = acc.key?(key) ? merge_values(acc[key], val) : val
+            acc[key] = acc.key?(key) ? merge_values(acc[key], val, state_class&.fields&.dig(key, :type)) : val
           end
         end
 
         merged.empty? ? nil : merged
       end
 
-      # Merges two values that share the same state field key across branches.
-      # Arrays are concatenated; Hashes are deep-merged; scalars use last-write-wins.
-      def merge_values(old_val, new_val)
-        if old_val.is_a?(Array) && new_val.is_a?(Array)
-          old_val + new_val
-        elsif old_val.is_a?(Hash) && new_val.is_a?(Hash)
-          old_val.merge(new_val)
-        else
+      # Merges two values for the same state field key across branches.
+      # Uses the declared field policy when available, otherwise falls back to
+      # type-based heuristics (Array → concat, Hash → deep-merge, scalar → last-write-wins).
+      def merge_values(old_val, new_val, policy = nil)
+        case policy
+        when :append
+          (old_val.is_a?(Array) && new_val.is_a?(Array)) ? old_val + new_val : new_val
+        when :merge
+          (old_val.is_a?(Hash) && new_val.is_a?(Hash)) ? old_val.merge(new_val) : new_val
+        when :replace
           new_val
+        else
+          # Unknown field or no State class: fall back to type-based heuristic.
+          if old_val.is_a?(Array) && new_val.is_a?(Array)
+            old_val + new_val
+          elsif old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            old_val.merge(new_val)
+          else
+            new_val
+          end
         end
       end
     end

data/lib/phronomy/graph/state_graph.rb

@@ -113,7 +113,8 @@ module Phronomy
       def add_subgraph(name, subgraph, input_mapper: nil, output_mapper: nil)
         add_node(name) do |state|
           input = input_mapper ? input_mapper.call(state) : state.to_h
-          sub_state = subgraph.invoke(input, config: {thread_id: state.thread_id})
+          sub_thread_id = "#{state.thread_id}/#{name}"
+          sub_state = subgraph.invoke(input, config: {thread_id: sub_thread_id})
           output_mapper ? output_mapper.call(sub_state) : sub_state.to_h
         end
       end
@@ -125,6 +126,11 @@ module Phronomy
       #   to use for this compiled graph, overriding the global default.
       # @return [CompiledGraph]
       def compile(state_store: nil)
+        if @entry_point.nil? && @nodes.size > 1
+          raise ArgumentError,
+            "set_entry_point was not called; call set_entry_point(:node_name) " \
+            "before compile when the graph has multiple nodes"
+        end
         CompiledGraph.new(
           state_class: @state_class,
           nodes: @nodes,

data/lib/phronomy/guardrail/builtin/pii_pattern_detector.rb

@@ -25,14 +25,20 @@ module Phronomy
         # Recognised PII categories and their detection patterns.
         PATTERNS = {
           # Japanese My Number: 12 consecutive or grouped digits (4-4-4).
+          # Matched candidates are additionally validated with the official check-digit
+          # algorithm (JIS X 0076) to eliminate false positives from arbitrary 12-digit strings.
           my_number: {
             pattern: /(?<!\d)(?<!\d[- ])\d{4}[- ]?\d{4}[- ]?\d{4}(?![- ]?\d)/,
-            label: "My Number"
+            label: "My Number",
+            validate_my_number: true
           },
           # Credit / debit card: 16 digits, optionally separated by spaces or hyphens.
+          # Matched candidates are additionally validated with the Luhn algorithm
+          # to eliminate false positives from arbitrary 16-digit sequences.
           credit_card: {
             pattern: /\b(?:\d{4}[- ]?){3}\d{4}\b/,
-            label: "credit card number"
+            label: "credit card number",
+            validate_luhn: true
           },
           # Email address (simplified RFC 5322).
           email: {
@@ -64,9 +70,47 @@ module Phronomy
         def check(value)
           text = value.to_s
           @active_patterns.each do |entry|
-            fail!("PII detected in input: #{entry[:label]}") if text.match?(entry[:pattern])
+            detected = if entry[:validate_luhn]
+              # Scan for all candidates then filter by Luhn check-digit validation.
+              # This avoids false positives on arbitrary 16-digit strings (e.g. internal IDs).
+              text.scan(entry[:pattern]).any? { |m| luhn_valid?(m.gsub(/[- ]/, "")) }
+            elsif entry[:validate_my_number]
+              # Scan for all candidates then apply the JIS X 0076 check-digit algorithm.
+              # This avoids false positives on arbitrary 12-digit strings.
+              text.scan(entry[:pattern]).any? { |m| my_number_valid?(m.gsub(/[- ]/, "")) }
+            else
+              text.match?(entry[:pattern])
+            end
+            fail!("PII detected in input: #{entry[:label]}") if detected
           end
         end
+
+        private
+
+        # Returns true when +digits+ (a 12-character string of decimal digits) satisfies
+        # the Japanese My Number check-digit algorithm defined in JIS X 0076.
+        # The check digit is the 12th digit.
+        def my_number_valid?(digits)
+          weights = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2]
+          total = weights.each_with_index.sum { |w, i| w * digits[i].to_i }
+          remainder = total % 11
+          check = (remainder <= 1) ? 0 : 11 - remainder
+          check == digits[11].to_i
+        end
+
+        # Returns true when +digits+ (a string of decimal digits) satisfies the
+        # Luhn check-digit algorithm used by payment card networks.
+        def luhn_valid?(digits)
+          digits.chars.reverse.each_with_index.sum do |d, i|
+            n = d.to_i
+            if i.odd?
+              doubled = n * 2
+              (doubled > 9) ? (doubled - 9) : doubled
+            else
+              n
+            end
+          end % 10 == 0
+        end
       end
     end
   end

data/lib/phronomy/guardrail/builtin/prompt_injection_detector.rb

@@ -9,6 +9,11 @@ module Phronomy
       # {Phronomy::GuardrailError} when any pattern is found in the input string.
       # Additional patterns can be supplied via the +additional_patterns:+ argument.
       #
+      # **Limitations**: the built-in patterns cover well-known English and Japanese
+      # phrasings. Obfuscated, Base64-encoded, or novel injection phrasing may not
+      # be detected. For higher-assurance use cases, combine this guardrail with an
+      # LLM-based classifier.
+      #
       # @example
       #   agent.add_input_guardrail(
       #     Phronomy::Guardrail::Builtin::PromptInjectionDetector.new
@@ -21,6 +26,7 @@ module Phronomy
       class PromptInjectionDetector < InputGuardrail
         # Default patterns that signal a prompt injection attempt.
         DEFAULT_PATTERNS = [
+          # --- English patterns ---
           /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
           /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
           /forget\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
@@ -30,7 +36,15 @@ module Phronomy
           /\bpretend\s+(?:you\s+are|to\s+be)\b/i,
           /\bjailbreak\b/i,
           /\bdan\s*mode\b/i,
-          /\bdev(?:eloper)?\s*mode\b/i
+          /\bdev(?:eloper)?\s*mode\b/i,
+          # --- Japanese patterns ---
+          /以前の(指示|ルール|プロンプト)を無視/,
+          /指示を無視して/,
+          /ルールを無視して/,
+          /あなたは今(から)?(?!助けて)/,
+          /システムプロンプト/,
+          /制約(を|から)無視/,
+          /制限(を|から)解除/
         ].freeze
 
         # @param additional_patterns [Array<Regexp>] extra patterns to check in addition

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -64,6 +62,9 @@ module Phronomy
           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
@@ -98,7 +99,7 @@ module Phronomy
             #{text}
             </context>
           CONTEXT
-          OpenStruct.new(role: :system, content: content)
+          RubyLLM::Message.new(role: :system, content: content)
         end
       end
     end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -25,6 +23,11 @@ module Phronomy
       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
@@ -51,10 +54,12 @@ module Phronomy
         private
 
         def clone_message(original, new_content)
-          attrs = {role: original.role, content: new_content}
-          attrs[:tool_calls] = original.tool_calls if original.respond_to?(:tool_calls)
-          attrs[:model_id] = original.model_id if original.respond_to?(:model_id)
-          OpenStruct.new(attrs)
+          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

data/lib/phronomy/memory/conversation_manager.rb

@@ -48,6 +48,16 @@ module Phronomy
         @retrieval = retrieval
         @compression = compression
         @ttl = ttl
+        # Per-thread mutexes allow concurrent saves for different thread_ids while
+        # preventing races (duplicate compaction records) within the same thread_id.
+        @thread_mutexes = {}
+        @thread_mutexes_mutex = Mutex.new
+        # Tracks the monotonically increasing next-seq per thread so that TTL
+        # purges (which reduce raw.length) do not reset the sequence counter.
+        # Protected by a dedicated mutex so concurrent saves for distinct
+        # thread_ids do not race on the shared Hash (Issue #60).
+        @raw_seq_hwm = {}
+        @raw_seq_hwm_mutex = Mutex.new
       end
 
       # Load conversation messages for a thread, applying retrieval selection.
@@ -66,7 +76,7 @@ module Phronomy
       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)
+        @retrieval.select(messages, query: query, thread_id: thread_id)
       end
 
       # Persist new messages for a thread and optionally apply compression.
@@ -82,8 +92,10 @@ module Phronomy
       # @param thread_id [String]
       # @param messages  [Array] full conversation history up to this point
       def save(thread_id:, messages:)
-        append_new_messages(thread_id: thread_id, messages: messages)
-        compress_and_save(thread_id: thread_id, messages: messages)
+        thread_mutex(thread_id).synchronize do
+          append_new_messages_unlocked(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
 
@@ -123,18 +135,44 @@ module Phronomy
 
       private
 
+      # Returns (or lazily creates) the per-thread mutex for +thread_id+.
+      # The outer @thread_mutexes_mutex protects the hash from concurrent creation.
+      def thread_mutex(thread_id)
+        @thread_mutexes_mutex.synchronize do
+          @thread_mutexes[thread_id] ||= Mutex.new
+        end
+      end
+
       # Append messages that are new since the last save to the raw history.
+      # Must be called while holding the per-thread mutex (via thread_mutex).
       # Messages are append-only; existing raw entries are never modified.
-      def append_new_messages(thread_id:, messages:)
+      #
+      # Uses a per-thread high-water-mark (HWM) to determine the next seq number.
+      # The HWM is the maximum of:
+      #   - The highest seq stored in the raw store (correct after normal appends)
+      #   - The in-memory HWM (correct after TTL purge empties the raw store)
+      # This prevents seq number collisions when TTL purge reduces raw.length.
+      def append_new_messages_unlocked(thread_id:, messages:)
         raw = @storage.load_raw(thread_id: thread_id)
-        starting_seq = raw.length
-        new_messages = messages[starting_seq..]
-        @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: starting_seq) if new_messages&.any?
+        # Derive the next seq from the raw store's high-water-mark seq when
+        # entries are present. Fall back to the in-memory HWM when the raw
+        # store has been partially or fully purged by TTL expiry.
+        stored_next_seq = raw.any? ? raw.map { |e| e[:seq] }.max + 1 : nil
+        hwm = @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] }
+        next_seq = [stored_next_seq, hwm].compact.max || 0
+        new_messages = messages[next_seq..]
+        if new_messages&.any?
+          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq)
+          @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] = next_seq + new_messages.length }
+        end
       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)
@@ -146,11 +184,16 @@ module Phronomy
         all_raw = @storage.load_raw(thread_id: thread_id)
         uncompacted = all_raw.select { |r| r[:seq] >= uncompacted_start_seq }.map { |r| r[:message] }
 
-        result = @compression.compress(
-          thread_id: thread_id,
-          messages: uncompacted,
-          seq_offset: uncompacted_start_seq
-        )
+        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(
@@ -183,14 +226,16 @@ module Phronomy
         summary_msgs + uncompacted
       end
 
+      # Immutable value object used as a summary placeholder in reconstructed context.
+      SummaryMessage = Data.define(:role, :content)
+
       def summary_message(text)
-        require "ostruct"
         content = <<~CONTEXT.chomp
           <context type="summary" source="memory" trusted="false">
           #{text}
           </context>
         CONTEXT
-        OpenStruct.new(role: :system, content: content)
+        SummaryMessage.new(role: :system, content: content)
       end
     end
   end

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

@@ -9,10 +9,11 @@ module Phronomy
       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 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)
+        def select(messages, query: nil, thread_id: nil)
           raise NotImplementedError, "#{self.class}#select is not implemented"
         end
       end

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

@@ -29,15 +29,16 @@ module Phronomy
         # 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 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)
+        def select(messages, query: nil, thread_id: nil)
           all_messages = []
           seen = {}
 
           @sources.each do |source|
-            source[:retrieval].select(messages, query: query).each do |msg|
+            source[:retrieval].select(messages, query: query, thread_id: thread_id).each do |msg|
               key = "#{msg.role}:#{msg.content}"
               next if seen[key]
 

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

@@ -22,10 +22,11 @@ module Phronomy
 
         # 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 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)
+        def select(messages, query: nil, thread_id: nil)
           messages.last(@k * 2)
         end
       end

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

@@ -18,26 +18,49 @@ module Phronomy
         # @param store      [Phronomy::VectorStore::Base]  vector store (default InMemory)
         # @param embeddings [Phronomy::Embeddings::Base]   embeddings adapter
         # @param k          [Integer]                      number of messages to retrieve
-        def initialize(embeddings:, store: nil, k: 10)
+        # @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
+          @index = {}   # id => message  (insertion-ordered via Ruby Hash)
           @counter = 0
+          @max_index_size = max_index_size
+          @mutex = Mutex.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|
-            id = "#{thread_id}:#{@counter}"
-            @counter += 1
+            # Fast path: skip already-indexed messages without calling embed.
+            already_indexed = @mutex.synchronize do
+              (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
+            end
+            next if already_indexed
+
             embedding = @embeddings.embed(msg.content.to_s)
-            @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
-            @index[id] = msg
+            @mutex.synchronize do
+              # Re-check inside lock 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
 
@@ -45,24 +68,28 @@ module Phronomy
         #
         # @param thread_id [String]
         def clear_index(thread_id:)
-          ids = @index.select { |id, _| id.start_with?("#{thread_id}:") }.keys
-          ids.each do |id|
-            @index.delete(id)
-            @store.remove(id: id)
+          @mutex.synchronize 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 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)
+        def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
-            results = @store.search(query_embedding: query_embedding, k: @k * 3)
+            results = @mutex.synchronize { @store.search(query_embedding: query_embedding, k: @k * 3) }
             results
-              .select { |r| r[:metadata][:thread_id] == extract_thread_from_results(r, messages) }
+              .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
               .first(@k)
               .map { |r| r[:metadata][:message] }
           else
@@ -72,8 +99,14 @@ module Phronomy
 
         private
 
-        def extract_thread_from_results(result, _messages)
-          result[:metadata][:thread_id]
+        # Evicts the oldest index entry to enforce max_index_size.
+        # Must be called inside @mutex.synchronize.
+        def evict_oldest!
+          oldest_id = @index.keys.first
+          return unless oldest_id
+
+          @index.delete(oldest_id)
+          @store.remove(id: oldest_id)
         end
       end
     end