anima-core 1.4.0 → 1.5.0

data/lib/mneme/compressed_viewport.rb

@@ -1,204 +0,0 @@
-# frozen_string_literal: true
-
-module Mneme
-  # Builds a compressed viewport for Mneme's LLM context. Mneme sees
-  # conversation (user/agent messages and think events) but not mechanical
-  # execution (tool calls and responses). Tool calls are compressed to
-  # aggregate counters like `[4 tools called]`.
-  #
-  # The viewport is split into three zones separated by delimiters:
-  # - **Eviction zone** — messages about to leave the viewport (upper third)
-  # - **Middle zone** — messages in the middle of the viewport
-  # - **Recent zone** — the most recent messages (lower third)
-  #
-  # Zone boundaries are calculated WITH tool call tokens (they affect
-  # position), then tool calls are removed and replaced with counters.
-  #
-  # @example
-  #   viewport = Mneme::CompressedViewport.new(session, token_budget: 60_000)
-  #   viewport.render  #=> "── EVICTION ZONE ──\nmessage 42 User: ..."
-  class CompressedViewport
-    ZONE_DELIMITERS = {
-      eviction: "── EVICTION ZONE (upper third) ──",
-      middle: "── MIDDLE ZONE ──",
-      recent: "── RECENT ZONE (lower third) ──"
-    }.freeze
-
-    # @param session [Session] the session to build viewport for
-    # @param token_budget [Integer] total tokens available for Mneme's viewport
-    # @param from_message_id [Integer, nil] start from this message ID (inclusive);
-    #   when nil, uses the session's full viewport
-    def initialize(session, token_budget:, from_message_id: nil)
-      @session = session
-      @token_budget = token_budget
-      @from_message_id = from_message_id
-    end
-
-    # Renders the compressed viewport as a string ready for Mneme's LLM context.
-    #
-    # @return [String] compressed viewport with zone delimiters
-    def render
-      return "" if messages.empty?
-
-      zones = split_into_zones(messages)
-      render_zones(zones)
-    end
-
-    # @return [Array<Message>] the raw messages selected for this viewport
-    def messages
-      @messages ||= fetch_messages
-    end
-
-    private
-
-    # Fetches messages within token budget, starting from from_message_id.
-    # Walks oldest-first from the boundary so Mneme processes the eviction
-    # zone (oldest messages) rather than the recent zone. This ensures
-    # {Mneme::Runner#advance_boundary} advances past only the oldest third,
-    # preserving recent conversation context in the main viewport.
-    #
-    # Caches per-message token costs in @message_costs for reuse by split_into_zones.
-    #
-    # @return [Array<Message>] chronologically ordered (oldest first)
-    def fetch_messages
-      scope = @session.messages.context_messages
-
-      if @from_message_id
-        scope = scope.where("id >= ?", @from_message_id)
-      end
-
-      selected = []
-      @message_costs = {}
-      remaining = @token_budget
-
-      scope.reorder(id: :asc).each do |message|
-        cost = message_token_cost(message)
-        break if cost > remaining && selected.any?
-
-        selected << message
-        @message_costs[message.id] = cost
-        remaining -= cost
-      end
-
-      selected
-    end
-
-    # Splits messages into three zones by token count.
-    # Zone boundaries are calculated including ALL messages (tool calls count
-    # toward position), but zone assignment uses cumulative tokens.
-    #
-    # @return [Hash{Symbol => Array<Message>}] :eviction, :middle, :recent
-    def split_into_zones(messages)
-      costs = messages.map { |message| [message, @message_costs[message.id] || message_token_cost(message)] }
-      zone_size = costs.sum(&:last) / 3.0
-
-      result = {eviction: [], middle: [], recent: []}
-      cumulative = 0
-
-      costs.each do |message, cost|
-        cumulative += cost
-        result[zone_for_cumulative(cumulative, zone_size)] << message
-      end
-
-      result
-    end
-
-    # Renders zones with delimiters, compressing tool calls into counters.
-    #
-    # @param zones [Hash{Symbol => Array<Message>}]
-    # @return [String]
-    def render_zones(zones)
-      %i[eviction middle recent].flat_map { |name|
-        [ZONE_DELIMITERS[name], render_zone(zones[name])]
-      }.join("\n")
-    end
-
-    # Determines which zone an event belongs to based on cumulative token position.
-    #
-    # @param cumulative [Numeric] cumulative token count including this event
-    # @param zone_size [Float] token count per zone (total / 3)
-    # @return [Symbol] :eviction, :middle, or :recent
-    def zone_for_cumulative(cumulative, zone_size)
-      if cumulative <= zone_size
-        :eviction
-      elsif cumulative <= zone_size * 2
-        :middle
-      else
-        :recent
-      end
-    end
-
-    # Renders a single zone: conversation messages as full text, consecutive
-    # tool calls/responses compressed into `[N tools called]` counters.
-    # tool_response messages are intentionally silent — they affect zone boundaries
-    # via token cost but are not rendered; only tool_call messages increment the counter.
-    #
-    # @param zone_messages [Array<Message>]
-    # @return [String]
-    def render_zone(zone_messages)
-      lines = []
-      tool_count = 0
-
-      zone_messages.each do |message|
-        if conversation_message?(message) || think_message?(message)
-          lines << flush_tool_count(tool_count)
-          tool_count = 0
-          lines << render_message_line(message)
-        elsif message.message_type == "tool_call"
-          tool_count += 1
-        end
-      end
-
-      lines << flush_tool_count(tool_count)
-      lines.compact.join("\n")
-    end
-
-    # @return [Boolean] true if message is a user/agent/system message
-    def conversation_message?(message)
-      message.message_type.in?(Message::CONVERSATION_TYPES)
-    end
-
-    # Think messages are tool_call messages with tool_name == "think".
-    # They carry the agent's reasoning and are treated as conversation.
-    #
-    # @return [Boolean]
-    def think_message?(message)
-      message.message_type == "tool_call" && message.payload["tool_name"] == Message::THINK_TOOL
-    end
-
-    ROLE_LABELS = {
-      "user_message" => "User",
-      "agent_message" => "Assistant",
-      "system_message" => "System"
-    }.freeze
-
-    # Renders a single message as a transcript line.
-    #
-    # @param message [Message]
-    # @return [String]
-    def render_message_line(message)
-      prefix = "message #{message.id}"
-      data = message.payload
-      if think_message?(message)
-        "#{prefix} Think: #{data.dig("tool_input", "thoughts")}"
-      else
-        "#{prefix} #{ROLE_LABELS.fetch(message.message_type)}: #{data["content"]}"
-      end
-    end
-
-    # Returns a tool count string if any tools were called, nil otherwise.
-    #
-    # @param count [Integer] number of tool calls to flush
-    # @return [String, nil]
-    def flush_tool_count(count)
-      return if count == 0
-      "[#{count} #{(count == 1) ? "tool" : "tools"} called]"
-    end
-
-    # @return [Integer] token cost using cached count or heuristic
-    def message_token_cost(message)
-      cached = message.token_count
-      (cached > 0) ? cached : message.estimate_tokens
-    end
-  end
-end

data/lib/mneme/passive_recall.rb

@@ -1,138 +0,0 @@
-# frozen_string_literal: true
-
-module Mneme
-  # Passive recall — automatic memory surfacing triggered by Goal updates.
-  # When goals are created or updated, searches message history for related
-  # context and enqueues phantom tool_call/tool_response pairs via the
-  # PendingMessage pipeline.
-  #
-  # Phantom pairs are promoted into real Message records by
-  # {Session#promote_pending_messages!} between agent loop rounds, then
-  # ride the conveyor belt like regular messages — cached as part of the
-  # stable prefix, compressed by Mneme on eviction.
-  #
-  # @example Trigger after a goal update
-  #   Mneme::PassiveRecall.new(session).call
-  class PassiveRecall
-    # Estimated token overhead for a tool_use wrapper (name + input fields).
-    TOOL_PAIR_OVERHEAD_TOKENS = 50
-
-    # @param session [Session] the session whose goals drive recall
-    def initialize(session)
-      @session = session
-    end
-
-    # Searches message history using active goal descriptions as queries.
-    # Enqueues phantom recall pairs for new results not already recalled.
-    #
-    # @return [Integer] number of pending messages created
-    def call
-      goals = @session.goals.active.root.includes(:sub_goals)
-      return 0 if goals.empty?
-
-      search_terms = build_search_terms(goals)
-      return 0 if search_terms.blank?
-
-      results = Mneme::Search.query(search_terms, limit: Anima::Settings.recall_max_results)
-      results = filter_duplicates(results)
-
-      enqueue_pending_messages(results)
-    end
-
-    private
-
-    STOP_WORDS = Set.new(%w[
-      a an the is are was were be been being do does did
-      have has had in on at to for of and or but not with
-      this that it its by from as up out if about into
-      fix add create update remove implement check set get
-    ]).freeze
-
-    # Extracts meaningful keywords from active goals and joins with OR.
-    #
-    # @param goals [ActiveRecord::Relation<Goal>]
-    # @return [String] FTS5 OR-joined keywords
-    def build_search_terms(goals)
-      descriptions = goals.flat_map { |goal|
-        [goal.description] + goal.sub_goals.reject(&:completed?).map(&:description)
-      }
-
-      words = descriptions.join(" ")
-        .gsub(/[^a-zA-Z0-9\s-]/, "")
-        .downcase
-        .split
-        .uniq
-        .reject { |word| STOP_WORDS.include?(word) || word.length < 3 }
-
-      words.join(" OR ").truncate(500)
-    end
-
-    # Excludes results already in the viewport or already recalled (pending or promoted).
-    #
-    # @param results [Array<Mneme::Search::Result>]
-    # @return [Array<Mneme::Search::Result>]
-    def filter_duplicates(results)
-      viewport_ids = @session.viewport_message_ids.to_set
-
-      existing_recall_ids = @session.messages
-        .where(message_type: "tool_call")
-        .where("payload ->> 'tool_name' = ?", PendingMessage::RECALL_MEMORY_TOOL)
-        .pluck(:tool_use_id)
-        .to_set
-
-      pending_recall_ids = @session.pending_messages
-        .where(source_type: "recall")
-        .pluck(:source_name)
-        .map { |name| "recall_#{name}" }
-        .to_set
-
-      known_ids = existing_recall_ids | pending_recall_ids
-
-      results.reject { |result|
-        viewport_ids.include?(result.message_id) ||
-          known_ids.include?("recall_#{result.message_id}")
-      }
-    end
-
-    # Creates PendingMessages for each recall result.
-    #
-    # @param results [Array<Mneme::Search::Result>]
-    # @return [Integer] number of pending messages created
-    def enqueue_pending_messages(results)
-      messages_by_id = Message.where(id: results.map(&:message_id))
-        .includes(:session).index_by(&:id)
-
-      count = 0
-      remaining = (Anima::Settings.token_budget * Anima::Settings.recall_budget_fraction).to_i
-
-      results.each do |result|
-        snippet = format_snippet(result, messages_by_id)
-        cost = Message.estimate_token_count(snippet.bytesize) + TOOL_PAIR_OVERHEAD_TOKENS
-        break if cost > remaining && count > 0
-
-        @session.pending_messages.create!(
-          content: snippet,
-          source_type: "recall",
-          source_name: result.message_id.to_s
-        )
-
-        remaining -= cost
-        count += 1
-      end
-
-      count
-    end
-
-    # Formats a search result as a compact snippet.
-    #
-    # @param result [Mneme::Search::Result]
-    # @param messages_by_id [Hash{Integer => Message}] pre-fetched messages
-    # @return [String]
-    def format_snippet(result, messages_by_id)
-      msg = messages_by_id[result.message_id]
-      session_label = msg&.session&.name || "session ##{result.session_id}"
-      content = result.snippet.truncate(Anima::Settings.recall_max_snippet_tokens * Message::BYTES_PER_TOKEN)
-      "message #{result.message_id} (#{session_label}): #{content}"
-    end
-  end
-end