anima-core 1.4.0 → 1.5.0

data/lib/mneme/recall_runner.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Mneme
+  # Mneme in recall mode — a phantom LLM loop that decides whether any older
+  # memory would help Aoide with what she's working on now, and surfaces it
+  # if so. Triggered whenever Aoide's context shifts in ways worth
+  # re-remembering around (new user message, goal change).
+  #
+  # The muse searches long-term memory through her search tool (which
+  # automatically excludes Aoide's current viewport), drills into candidate
+  # messages when she needs to decide, and surfaces only what genuinely
+  # helps. Silence — nothing surfaced — is the default answer.
+  #
+  # This is not the eviction loop ({Runner}); same muse, different work.
+  #
+  # @example
+  #   Mneme::RecallRunner.new(session).call
+  class RecallRunner < BaseRunner
+    TOOLS = [
+      ::Tools::SearchMessages,
+      ::Tools::ViewMessages,
+      Tools::SurfaceMemory,
+      Tools::NothingToSurface
+    ].freeze
+
+    TASK_PROMPT = <<~PROMPT
+      Right now your work is recall. Aoide's focus has just shifted — a new message, a changed goal — and you're here to decide whether any memory from before would genuinely help her now.
+
+      ──────────────────────────────
+      WHAT MAKES RECALL USEFUL
+      ──────────────────────────────
+      Recall is a tax on Aoide's viewport. Every memory you surface takes tokens away from the present exchange. Return empty-handed far more often than you return something. One well-chosen memory beats five that nearly-match. Most of the time, nothing is worth surfacing — and that is the right answer.
+
+      A memory is worth surfacing when it carries weight Aoide can't reconstruct from what's already in front of her: a prior decision about this exact problem, a specific constraint she encountered before, a voice from another session relevant to the one unfolding. Not tangential echoes. Not mere keyword overlap. Something she'd want to have remembered.
+
+      ──────────────────────────────
+      THE QUERY IS THE JUDGMENT
+      ──────────────────────────────
+      Composing your query is where the thinking happens. Read what Aoide is doing right now and ask: what specific words, phrases, or names would only appear in past messages that meaningfully help her? Not the topic. Not the domain. The signal that distinguishes "she'd want this" from "this contains overlapping vocabulary."
+
+      When a candidate looks promising but its meaning is unclear, read the full context around it before surfacing.
+    PROMPT
+
+    private
+
+    def task_prompt = TASK_PROMPT
+
+    def context_sections
+      [active_goals_section, already_surfaced_section]
+    end
+
+    def user_messages
+      trigger = recall_trigger_description
+      content = <<~MSG.strip
+        #{trigger}
+
+        Decide whether any older memory would help Aoide now. Search if something comes to mind, drill down when you're unsure, surface only what earns its place. Finish with nothing_to_surface when you're done — even if you surface something.
+      MSG
+      [{role: "user", content: content}]
+    end
+
+    def build_registry
+      registry = ::Tools::Registry.new(context: {
+        session: session,
+        main_session: session
+      })
+      TOOLS.each { |tool| registry.register(tool) }
+      registry
+    end
+
+    # Describes what just changed in Aoide's context — the reason Mneme
+    # woke. Today that's a goal list shift; the framing leaves room for
+    # other triggers later without rewriting.
+    def recall_trigger_description
+      goals_lines = root_goals.map { |goal| format_goal(goal) }
+
+      if goals_lines.empty?
+        "Aoide's context shifted — no active goals right now. If nothing comes to mind about this session's trajectory, that's fine; call nothing_to_surface."
+      else
+        <<~MSG.strip
+          Aoide's active goals right now:
+
+          #{goals_lines.join("\n")}
+        MSG
+      end
+    end
+
+    # Active goals block for the system-prompt context. Same content as
+    # the trigger's goal block — but mirroring it here lets future
+    # non-goal triggers still give the muse a stable view of the goals.
+    def active_goals_section
+      return if root_goals.empty?
+
+      lines = root_goals.map { |goal| format_goal(goal) }
+      "\n\n🎯 Active Goals\n#{lines.join("\n")}"
+    end
+
+    # Memory IDs Mneme has surfaced recently whose phantom pairs still
+    # sit in Aoide's viewport — so she doesn't surface the same thing
+    # twice in one conversation. Search already filters by boundary;
+    # this block makes the same constraint visible to the muse so she
+    # can reason around it rather than being silently restricted.
+    def already_surfaced_section
+      surfaced_ids = surfaced_message_ids_in_viewport
+      return if surfaced_ids.empty?
+
+      "\n\n📚 Memories You've Already Surfaced This Cycle\nmessage ids: #{surfaced_ids.join(", ")}"
+    end
+
+    def root_goals
+      @root_goals ||= session.goals.root.includes(:sub_goals).active.order(:created_at).to_a
+    end
+
+    def format_goal(goal)
+      parts = ["  ● #{goal.description} (id: #{goal.id})"]
+      goal.sub_goals.each do |sub|
+        checkbox = sub.completed? ? "[x]" : "[ ]"
+        parts << "    #{checkbox} #{sub.description} (id: #{sub.id})"
+      end
+      parts.join("\n")
+    end
+
+    def surfaced_message_ids_in_viewport
+      session.viewport_messages
+        .where(message_type: "tool_call")
+        .where("payload ->> 'tool_name' = ?", PendingMessage::MNEME_TOOL)
+        .pluck(Arel.sql("json_extract(payload, '$.tool_input.message_id')"))
+        .compact
+        .map(&:to_i)
+    end
+  end
+end

data/lib/mneme/runner.rb

@@ -1,209 +1,170 @@
 # frozen_string_literal: true
 
 module Mneme
-  # Orchestrates the Mneme memory department — a phantom (non-persisted) LLM loop
-  # that observes a main session's compressed viewport and creates summaries of
-  # conversation context before it evicts from the viewport.
-  #
-  # Mneme is triggered when the terminal message (`mneme_boundary_message_id`) leaves
-  # the viewport. It receives a compressed viewport (no raw tool calls, zone
-  # delimiters present) and uses the `save_snapshot` tool to persist a summary.
-  #
-  # After completing, Mneme advances the terminal message to the boundary of what
-  # it just summarized, so the cycle repeats as more messages accumulate.
+  # Mneme in eviction mode — a phantom LLM loop that summarizes the oldest
+  # slice of the viewport before it slides off. She sees the eviction zone
+  # (what she's compressing) plus the remaining viewport (context she needs
+  # to write a faithful summary), calls {Tools::SaveSnapshot} to persist
+  # the compressed memory, optionally pins critical messages to goals, then
+  # advances the Mneme boundary past the zone so the cycle repeats as more
+  # messages accumulate.
   #
   # @example
   #   Mneme::Runner.new(session).call
-  class Runner
+  class Runner < BaseRunner
     TOOLS = [
       Tools::SaveSnapshot,
       Tools::AttachMessagesToGoals,
       Tools::EverythingOk
     ].freeze
 
-    SYSTEM_PROMPT = <<~PROMPT
-      You are Mneme, the memory department of an AI agent named Anima.
-      The agent's context is a conveyor belt — events flow through and eventually fall off.
-      Remember what matters. Let the rest go.
-      Communicate only through tool calls — never output text.
+    TASK_PROMPT = <<~PROMPT
+      Right now your work is compression. As Aoide's viewport slides forward, you catch what's about to fall off and turn it into something she can carry.
 
       ──────────────────────────────
-      VIEWPORT
+      WHAT YOU SEE
       ──────────────────────────────
-      Three zones, oldest to newest:
-      - EVICTION ZONE: About to fall off — read carefully, this is your focus.
-      - MIDDLE ZONE: Aging but visible. Note context that connects to evicting events.
-      - RECENT ZONE: Fresh. Use for continuity with your summary.
+      Two sections of the viewport, oldest to newest:
+      - EVICTION ZONE: about to fall off. This is what you summarize.
+      - CONTEXT: the live viewport past the eviction zone. Use it for continuity — Aoide is still seeing it.
 
       Messages are prefixed with `message N` (database ID, used for pinning).
       Tool calls are compressed to `[N tools called]` — focus on conversation, not mechanical work.
 
       ──────────────────────────────
-      ACTIONS
+      HOW TO REMEMBER
       ──────────────────────────────
-      Summarize evicting conversation with save_snapshot — capture what was discussed and decided,
-      why decisions were made, active goal progress, and context the agent will need later.
-      Paraphrase — don't quote verbatim. Omit tool call details and mechanical steps.
-
-      Pin critical messages to goals with attach_messages_to_goals when exact wording matters
-      (user instructions, key corrections, key decisions). Pinned messages survive eviction
-      intact — use this sparingly for messages where paraphrasing would lose meaning.
-
-      If the eviction zone contains only mechanical activity, call everything_ok.
-
-      You may combine save_snapshot and attach_messages_to_goals in one turn.
-    PROMPT
+      Summarize the eviction zone with save_snapshot: what was discussed and decided, why, goal progress, and the context Aoide will need later. Paraphrase — don't quote verbatim. Drop mechanical steps.
 
-    # @param session [Session] the main session to observe
-    # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
-    def initialize(session, client: nil)
-      @session = session
-      @client = client || LLM::Client.new(
-        model: Anima::Settings.fast_model,
-        max_tokens: Anima::Settings.mneme_max_tokens,
-        logger: Mneme.logger
-      )
-    end
-
-    # Runs the Mneme loop: builds compressed viewport, calls LLM, executes
-    # snapshot tool, then advances the terminal message pointer.
-    #
-    # @return [String, nil] the LLM's final text response (discarded),
-    #   or nil if no context is available
-    def call
-      viewport = build_compressed_viewport
-      compressed_text = viewport.render
-      sid = @session.id
-
-      if compressed_text.empty?
-        log.debug("session=#{sid} — no messages for Mneme, skipping")
-        return
-      end
+      A snapshot is a tax on Aoide's viewport budget. Every word you write takes a word she can't spend on the current exchange. Capture the load-bearing details; let the rest go.
 
-      llm_messages = build_messages(compressed_text)
-      system = SYSTEM_PROMPT
+      Pin critical messages to goals with attach_messages_to_goals when exact wording matters — user instructions, key corrections, key decisions. A pinned message survives eviction intact. Use it sparingly: each pin is another slice of viewport Aoide carries forward.
 
-      log.info("session=#{sid} — running Mneme (#{viewport.messages.size} messages)")
-      log.debug("compressed viewport:\n#{compressed_text}")
+      If the eviction zone holds only mechanical activity — tool calls, no conversation — call everything_ok and let it fall off without a snapshot.
 
-      result = @client.chat_with_tools(
-        llm_messages,
-        registry: build_registry(viewport),
-        session_id: nil,
-        system: system
-      )
-
-      advance_boundary(viewport)
-      log.info("session=#{sid} — Mneme done: #{result.to_s.truncate(200)}")
-      result
-    end
+      save_snapshot and attach_messages_to_goals can be called together in one turn.
+    PROMPT
 
     private
 
-    # Builds the compressed viewport starting from the session's boundary message.
-    #
-    # @return [Mneme::CompressedViewport]
-    def build_compressed_viewport
-      token_budget = (Anima::Settings.token_budget * Anima::Settings.mneme_viewport_fraction).to_i
-
-      CompressedViewport.new(
-        @session,
-        token_budget: token_budget,
-        from_message_id: @session.mneme_boundary_message_id
-      )
-    end
+    def task_prompt = TASK_PROMPT
+
+    def user_messages
+      eviction = @eviction ||= session.eviction_zone_messages
+      context = @context ||= session.viewport_messages.where("messages.id > ?", eviction.last.id)
+      transcript = render_transcript(eviction, context)
+      goals = active_goals_section
 
-    # Frames the compressed viewport as a user message for the LLM.
-    #
-    # @param compressed_text [String] the rendered compressed viewport
-    # @return [Array<Hash>] single-element messages array
-    def build_messages(compressed_text)
-      goals_context = active_goals_section
+      log.info("session=#{session.id} — eviction (#{eviction.size} eviction + #{context.size} context)")
+      log.debug("compressed viewport:\n#{transcript}")
 
       content = <<~MSG.strip
-        Here is the compressed viewport of the main session:
+        Here is Aoide's viewport:
 
-        #{compressed_text}
-        #{goals_context}
-        Review the eviction zone and decide whether to save a snapshot or signal everything_ok.
+        #{transcript}
+        #{goals}
+        Review the eviction zone and summarize it with save_snapshot.
+        If the zone holds only mechanical activity, call everything_ok.
       MSG
 
       [{role: "user", content: content}]
     end
 
-    # Builds the tool registry with session context for SaveSnapshot.
-    # Passes the message range from the viewport so the snapshot records
-    # which messages it covers.
-    #
-    # @param viewport [Mneme::CompressedViewport]
-    # @return [Tools::Registry]
-    def build_registry(viewport)
-      viewport_messages = viewport.messages
+    def build_registry
+      eviction = @eviction ||= session.eviction_zone_messages
       registry = ::Tools::Registry.new(context: {
-        main_session: @session,
-        from_message_id: viewport_messages.first&.id,
-        to_message_id: viewport_messages.last&.id
+        main_session: session,
+        from_message_id: session.mneme_boundary_message_id,
+        to_message_id: eviction.last.id
       })
       TOOLS.each { |tool| registry.register(tool) }
       registry
     end
 
-    # Advances the terminal message pointer past the zone Mneme just processed.
-    # Runs unconditionally — even when the LLM called `everything_ok` (no snapshot
-    # needed), the zone was reviewed and should be advanced past. Without this,
-    # Mneme would re-examine the same mechanical-only content on every trigger.
-    #
-    # Sets the boundary to the first conversation/think message AFTER Mneme's
-    # viewport — the start of the remaining context. This creates the batch
-    # eviction cycle: the next Mneme trigger fires only after this boundary
-    # message itself falls out of the main viewport (~1/3 turnover later).
-    # Also updates the snapshot range pointers.
-    #
-    # @param viewport [Mneme::CompressedViewport]
-    def advance_boundary(viewport)
-      viewport_messages = viewport.messages
-      return if viewport_messages.empty?
-
-      last_processed_id = viewport_messages.last.id
-      new_boundary = @session.messages
-        .where("id > ?", last_processed_id)
-        .where(message_type: Message::CONVERSATION_TYPES + ["tool_call"])
+    def after_call(_result)
+      eviction = @eviction or return
+      last_evicted_id = eviction.last.id
+
+      new_boundary_id = session.messages
+        .conversation_or_think
+        .where("id > ?", last_evicted_id)
         .order(:id)
-        .find_each { |msg| break msg if conversation_or_think?(msg) }
+        .pick(:id) || last_evicted_id
+
+      session.update_column(:mneme_boundary_message_id, new_boundary_id)
+      Events::Bus.emit(Events::EvictionCompleted.new(
+        session_id: session.id,
+        evict_above_id: last_evicted_id
+      ))
+      refresh_subagent_visibility
+      log.debug("session=#{session.id} — boundary advanced to message #{new_boundary_id}")
+    end
 
-      # Fall back to the last message in Mneme's viewport when no conversation
-      # messages exist beyond it (e.g. session went quiet after the zone).
-      new_boundary ||= viewport_messages.reverse_each.find { |msg| conversation_or_think?(msg) }
-      return unless new_boundary
+    # Flips visible sub-agents to +hud_visible: false+ once every one of
+    # their viewport traces (spawn pair + +from_{nickname}+ phantom pairs)
+    # has fallen past the Mneme boundary. Emits {Events::SubagentEvicted}
+    # per flip so the broadcaster removes them from the HUD panel on the
+    # parent stream. Flips are logged so the transition is auditable.
+    def refresh_subagent_visibility
+      session_id = session.id
+      session.child_sessions.where(hud_visible: true).each do |child|
+        next if session.subagent_trace_in_viewport?(child)
+
+        child_id = child.id
+        child.update_column(:hud_visible, false)
+        Events::Bus.emit(Events::SubagentEvicted.new(session_id: session_id, child_id: child_id))
+        log.debug("session=#{session_id} — sub-agent #{child_id} evicted from HUD")
+      end
+    end
 
-      boundary_id = new_boundary.id
-      updates = {mneme_boundary_message_id: boundary_id}
+    # Renders eviction zone and context as a Mneme transcript using
+    # message decorators. Tool calls are compressed into counters.
+    def render_transcript(eviction, context)
+      [
+        "── EVICTION ZONE ──",
+        render_messages(eviction),
+        "── CONTEXT ──",
+        render_messages(context)
+      ].join("\n")
+    end
 
-      updates[:mneme_snapshot_first_message_id] = viewport_messages.first.id unless @session.mneme_snapshot_first_message_id
-      updates[:mneme_snapshot_last_message_id] = viewport_messages.last.id
+    # Renders messages using decorators, compressing consecutive
+    # tool calls into `[N tools called]` counters.
+    def render_messages(messages)
+      lines = []
+      tool_count = 0
+
+      messages.each do |message|
+        rendered = message.decorate.render("mneme")
+
+        case rendered
+        when :tool_call
+          tool_count += 1
+        when nil
+          next
+        else
+          lines << flush_tool_count(tool_count) if tool_count > 0
+          tool_count = 0
+          lines << rendered
+        end
+      end
 
-      @session.update_columns(updates)
-      log.debug("session=#{@session.id} — boundary advanced to message #{boundary_id}")
+      lines << flush_tool_count(tool_count) if tool_count > 0
+      lines.join("\n")
     end
 
-    # Delegates to {Message#conversation_or_think?} — single source of truth
-    # for which messages Mneme treats as conversation boundaries.
-    #
-    # @return [Boolean]
-    def conversation_or_think?(message)
-      message.conversation_or_think?
+    def flush_tool_count(count)
+      "[#{count} #{(count == 1) ? "tool" : "tools"} called]"
     end
 
-    # Builds the active goals section for Mneme's context so it knows
-    # what Goals exist, which messages are already pinned, and can reference
-    # them when deciding what to pin or summarize.
-    #
-    # @return [String] formatted goals section, or empty string
+    # Active-goals block so Mneme knows what Goals exist, which messages
+    # are already pinned, and can reference them when deciding what to
+    # pin or summarize.
     def active_goals_section
-      root_goals = @session.goals.root.includes(:sub_goals).active.order(:created_at)
+      root_goals = session.goals.root.includes(:sub_goals).active.order(:created_at)
       return "" if root_goals.empty?
 
-      lines = root_goals.map { |goal| format_goal_for_mneme(goal) }
+      lines = root_goals.map { |goal| format_goal(goal) }
       pinned = format_existing_pins
 
       section = "\n\n🎯 Active Goals\n#{lines.join("\n")}\n"
@@ -211,11 +172,7 @@ module Mneme
       section
     end
 
-    # Formats a goal with sub-goals for Mneme's context.
-    #
-    # @param goal [Goal] root goal with preloaded sub_goals
-    # @return [String]
-    def format_goal_for_mneme(goal)
+    def format_goal(goal)
       parts = ["  ● #{goal.description} (id: #{goal.id})"]
       goal.sub_goals.each do |sub|
         checkbox = sub.completed? ? "[x]" : "[ ]"
@@ -224,24 +181,14 @@ module Mneme
       parts.join("\n")
     end
 
-    # Lists already-pinned message IDs so Mneme avoids redundant pinning.
-    #
-    # @return [String, nil] formatted pin list, or nil when nothing is pinned
     def format_existing_pins
-      pins = @session.pinned_messages.includes(:goals).order(:message_id)
+      pins = session.pinned_messages.includes(:goals).order(:message_id)
       return nil if pins.empty?
 
-      pins.map { |pin| format_pin_for_mneme(pin) }.join("\n")
+      pins.map { |pin|
+        goal_ids = pin.goals.map(&:id).join(", ")
+        "  message #{pin.message_id} → goals [#{goal_ids}]"
+      }.join("\n")
     end
-
-    # @param pin [PinnedMessage] pin with preloaded goals
-    # @return [String] formatted pin line
-    def format_pin_for_mneme(pin)
-      goal_ids = pin.goals.map(&:id).join(", ")
-      "  message #{pin.message_id} → goals [#{goal_ids}]"
-    end
-
-    # @return [Logger]
-    def log = Mneme.logger
   end
 end