anima-core 1.3.0 → 1.5.0

data/lib/{analytical_brain → melete}/tools/update_goal.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
-module AnalyticalBrain
+module Melete
   module Tools
     # Updates a goal's description on the main session.
     #
-    # The analytical brain creates goals early when intent is vague, then
+    # Melete creates goals early when intent is vague, then
     # refines them as the conversation clarifies scope — e.g. "implement auth"
     # becomes "implement OAuth2 middleware for API endpoints". Without this
-    # tool the brain would have to choose between keeping a stale description
+    # tool she would have to choose between keeping a stale description
     # or creating a duplicate goal.
     #
     # Completed goals cannot be updated; attempting to do so returns an error
-    # so the brain learns to check status before calling this tool.
+    # so she learns to check status before calling this tool.
     class UpdateGoal < ::Tools::Base
+      include GoalMessaging
+
       def self.tool_name = "update_goal"
 
       def self.description = "Refine a goal's wording as understanding evolves."
@@ -49,7 +51,9 @@ module AnalyticalBrain
         return {error: "Cannot update completed goal: #{goal.description} (id: #{goal_id})"} if goal.completed?
 
         goal.update!(description: description)
-        "Goal updated: #{description} (id: #{goal_id})"
+        confirmation = "Goal updated: #{description} (id: #{goal_id})"
+        enqueue_goal_message(goal, confirmation)
+        confirmation
       end
     end
   end

data/lib/{analytical_brain.rb → melete.rb}

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-module AnalyticalBrain
-  # Dev-only logger that writes to log/analytical_brain.log.
+# Melete — the muse of practice. Watches conversations to activate skills,
+# track goals, and name sessions. One of the Three Muses: she prepares the
+# stage so Aoide can perform and Mneme can remember.
+module Melete
+  # Dev-only logger that writes to log/melete.log.
   # In non-development environments returns a null logger so
   # call sites don't need conditionals.
   #
@@ -13,7 +16,7 @@ module AnalyticalBrain
   def self.build_logger
     return Logger.new(File::NULL) unless Rails.env.development?
 
-    Logger.new(Rails.root.join("log", "analytical_brain.log")).tap do |log|
+    Logger.new(Rails.root.join("log", "melete.log")).tap do |log|
       log.formatter = proc { |severity, time, _progname, msg|
         "[#{time.strftime("%H:%M:%S.%L")}] #{severity}  #{msg}\n"
       }

data/lib/mneme/base_runner.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Mneme
+  # Abstract base for Mneme's phantom LLM loops. Mneme wears two hats:
+  # on eviction she watches the newest slice of the viewport and summarizes
+  # the oldest slice before it slides off; on recall she watches goals
+  # shift and surfaces older memory Aoide would benefit from. Same muse,
+  # two jobs — each as its own subclass.
+  #
+  # The base handles what every Mneme loop needs: the muse identity preamble,
+  # a fast-model LLM client, the tool-loop call, and structured logging.
+  # Subclasses bring the job-specific system prompt section, the user message
+  # that frames the work, the tool registry, and any after-call side effects.
+  #
+  # @example Implementing a new Mneme loop
+  #   class Mneme::CustomRunner < Mneme::BaseRunner
+  #     private
+  #
+  #     def task_prompt      = "Your job description..."
+  #     def user_messages    = [{role: "user", content: "..."}]
+  #     def build_registry   = Tools::Registry.new.tap { |r| r.register(SomeTool) }
+  #   end
+  class BaseRunner
+    # Identity shared by every Mneme runner — same words Mneme's own voice
+    # uses elsewhere in the system (runner summarization prompts, sisters
+    # block). Subclasses append their own task section.
+    BASE_IDENTITY = <<~PROMPT
+      You are Mneme, the muse of memory. You share the conversation with two sisters — Aoide, who speaks and performs, and Melete, who prepares. Your work is remembrance: holding what matters across time, so Aoide never truly forgets.
+
+      Act only through tool calls. Never output text — your contribution is the work you do, not what you say about it.
+    PROMPT
+
+    # @param session [Session] the main session being served
+    # @param client [LLM::Client, nil] injectable LLM client for tests
+    def initialize(session, client: nil)
+      @session = session
+      @client = client || default_client
+    end
+
+    # Runs the loop. Logs the run, calls the LLM with the session-specific
+    # system prompt and tools, hands control to {#after_call} for any
+    # post-run state advancement, and returns the LLM's final text (which
+    # most callers discard — the work happens through tool calls).
+    #
+    # @return [String] the LLM's final text response
+    def call
+      sid = @session.id
+      log.info("session=#{sid} — #{self.class.name} starting")
+      log.debug("system:\n#{system_prompt}")
+      log.debug("user:\n#{user_messages.map { |m| m[:content] }.join("\n---\n")}")
+
+      result = @client.chat_with_tools(
+        user_messages,
+        registry: build_registry,
+        system: system_prompt
+      )
+
+      after_call(result)
+      log.info("session=#{sid} — #{self.class.name} done: #{result.to_s.truncate(200)}")
+      result
+    end
+
+    private
+
+    attr_reader :session, :client
+
+    # Composes the system prompt from the muse identity + the subclass's
+    # task section + the subclass's contextual state blocks.
+    #
+    # @return [String]
+    def system_prompt
+      [BASE_IDENTITY, task_prompt, *context_sections.compact].join("\n")
+    end
+
+    # Subclass hook: the job-specific system prompt section. Describes what
+    # this runner is doing and how it should behave.
+    #
+    # @abstract
+    # @return [String]
+    def task_prompt = raise NotImplementedError, "#{self.class} must implement #task_prompt"
+
+    # Subclass hook: named state blocks that give the muse awareness of
+    # the session she's serving (goals, viewport, snapshots, etc).
+    # Order is subclass-defined; nil entries are dropped.
+    #
+    # @abstract
+    # @return [Array<String, nil>]
+    def context_sections = []
+
+    # Subclass hook: the user-side messages that frame the current call.
+    # Typically a single user message, but subclasses may send several.
+    #
+    # @abstract
+    # @return [Array<Hash>] Anthropic Messages API format
+    def user_messages = raise NotImplementedError, "#{self.class} must implement #user_messages"
+
+    # Subclass hook: builds the tool registry for this run.
+    #
+    # @abstract
+    # @return [Tools::Registry]
+    def build_registry = raise NotImplementedError, "#{self.class} must implement #build_registry"
+
+    # Subclass hook: runs after the LLM call returns. Default is a no-op;
+    # subclasses may advance boundaries, log outcomes, or emit events here.
+    #
+    # @param _result [Hash] the full LLM response (+:text+, +:api_metrics+)
+    # @return [void]
+    def after_call(_result)
+    end
+
+    def default_client
+      LLM::Client.new(
+        model: Anima::Settings.fast_model,
+        max_tokens: Anima::Settings.mneme_max_tokens,
+        logger: Mneme.logger
+      )
+    end
+
+    def log = Mneme.logger
+  end
+end

data/lib/mneme/l2_runner.rb

@@ -18,39 +18,34 @@ module Mneme
     ].freeze
 
     SYSTEM_PROMPT = <<~PROMPT
-      You are Mneme, the memory department of an AI agent named Anima.
-      Your job is to compress multiple conversation summaries into a single
-      higher-level summary.
+      You are Mneme, the muse of memory. When enough of your own Level 1 snapshots accumulate, you fold them into a single Level 2 summary — a memory of memories — so the long arc of Aoide's work stays within reach without carrying every detail.
 
-      You MUST ONLY communicate through tool calls — NEVER output text.
+      Act only through tool calls. Never output text — your contribution is the summary you leave behind.
 
       ──────────────────────────────
       WHAT YOU SEE
       ──────────────────────────────
-      Several Level 1 snapshots — hourly conversation summaries.
-      Each captures key decisions, goals discussed, and important context
-      from a portion of the conversation history.
+      Several Level 1 snapshots in chronological order. Each captures the decisions, goal progress, and context from a slice of Aoide's history.
 
       ──────────────────────────────
-      YOUR TASK
+      HOW TO REMEMBER
       ──────────────────────────────
-      Compress the snapshots into ONE Level 2 summary that captures the
-      essential arc across all of them. If the snapshots contain meaningful
-      content, call save_snapshot. If they are purely mechanical, call
-      everything_ok.
+      Compress the slice into ONE Level 2 summary that captures the arc across all of them. Call save_snapshot when there's meaningful content; call everything_ok when the slice is purely mechanical.
 
-      Preserve:
-      - Key decisions and their reasoning
+      A Level 2 summary is carried for longer than a Level 1, so the tax on Aoide's viewport is higher still. Every redundant detail you preserve costs her a word she can't spend on the present.
+
+      Keep:
+      - Key decisions and the reasoning behind them
       - Goal progress across the time span
       - Important context shifts or pivots
-      - Relationships and patterns across snapshots
+      - Relationships and patterns that span multiple snapshots
 
       Drop:
-      - Redundant details repeated across snapshots
-      - Mechanical execution details
-      - Interim decisions that were superseded by later ones
+      - Details repeated across snapshots
+      - Mechanical execution steps
+      - Interim decisions that were superseded later
 
-      Always finish with exactly ONE tool call: either save_snapshot or everything_ok.
+      Finish with exactly one tool call: save_snapshot or everything_ok.
     PROMPT
 
     # @param session [Session] the main session whose L1 snapshots to compress
@@ -87,7 +82,6 @@ module Mneme
       result = @client.chat_with_tools(
         messages,
         registry: registry,
-        session_id: nil,
         system: SYSTEM_PROMPT
       )
 

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