anima-core 1.1.3 → 1.3.0

data/lib/mneme/passive_recall.rb

@@ -32,8 +32,8 @@ module Mneme
 
       # Exclude events from the current session's viewport — no point recalling
       # what the agent already sees.
-      viewport_ids = @session.viewport_event_ids.to_set
-      results.reject { |result| viewport_ids.include?(result.event_id) }
+      viewport_ids = @session.viewport_message_ids.to_set
+      results.reject { |result| viewport_ids.include?(result.message_id) }
     end
 
     private

data/lib/mneme/runner.rb

@@ -5,71 +5,53 @@ module Mneme
   # 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 event (`mneme_boundary_event_id`) leaves
+  # 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 event to the boundary of what
-  # it just summarized, so the cycle repeats as more events accumulate.
+  # After completing, Mneme advances the terminal message to the boundary of what
+  # it just summarized, so the cycle repeats as more messages accumulate.
   #
   # @example
   #   Mneme::Runner.new(session).call
   class Runner
     TOOLS = [
       Tools::SaveSnapshot,
-      Tools::AttachEventsToGoals,
+      Tools::AttachMessagesToGoals,
       Tools::EverythingOk
     ].freeze
 
     SYSTEM_PROMPT = <<~PROMPT
       You are Mneme, the memory department of an AI agent named Anima.
-      Your job is to create concise summaries of conversation context that is
-      about to leave the agent's context window.
-
-      You MUST ONLY communicate through tool calls — NEVER output text.
+      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.
 
       ──────────────────────────────
-      WHAT YOU SEE
+      VIEWPORT
       ──────────────────────────────
-      A compressed viewport with three zones:
-      - EVICTION ZONE: Events about to leave the viewport. Summarize these.
-      - MIDDLE ZONE: Events still visible but aging. Note key context.
-      - RECENT ZONE: Fresh events. Use for continuity with the summary.
+      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.
 
-      Events are prefixed with `event N` (their database ID).
-      Tool calls are compressed to `[N tools called]` — the mechanical work
-      is not important, only the conversation flow.
+      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.
 
       ──────────────────────────────
-      YOUR TASK
+      ACTIONS
       ──────────────────────────────
-      1. Read the eviction zone carefully.
-      2. If it contains meaningful conversation (decisions, goals, context):
-         Call save_snapshot with a concise summary.
-      3. If any events in the eviction zone are too important to summarize
-         (exact user instructions, critical corrections, key decisions),
-         pin them to active goals with attach_events_to_goals.
-         Pinned events survive eviction intact — use this sparingly for
-         events where the exact wording matters.
-      4. If it contains only mechanical activity with no conversation:
-         Call everything_ok.
-
-      You may call BOTH save_snapshot AND attach_events_to_goals in one turn
-      when the zone has a mix of summarizable and pin-worthy events.
-
-      Write summaries that capture:
-      - What was discussed and decided
-      - Why decisions were made
-      - Active goals and their progress
-      - Key context the agent would need later
-
-      Do NOT include:
-      - Tool call details (which files were read, commands run)
-      - Mechanical execution steps
-      - Verbatim quotes (paraphrase instead)
-
-      Always finish with at least one tool call: save_snapshot, attach_events_to_goals,
-      or everything_ok. You may combine save_snapshot with attach_events_to_goals.
+      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
 
     # @param session [Session] the main session to observe
@@ -84,7 +66,7 @@ module Mneme
     end
 
     # Runs the Mneme loop: builds compressed viewport, calls LLM, executes
-    # snapshot tool, then advances the terminal event pointer.
+    # 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
@@ -94,18 +76,18 @@ module Mneme
       sid = @session.id
 
       if compressed_text.empty?
-        log.debug("session=#{sid} — no events for Mneme, skipping")
+        log.debug("session=#{sid} — no messages for Mneme, skipping")
         return
       end
 
-      messages = build_messages(compressed_text)
+      llm_messages = build_messages(compressed_text)
       system = SYSTEM_PROMPT
 
-      log.info("session=#{sid} — running Mneme (#{viewport.events.size} events)")
+      log.info("session=#{sid} — running Mneme (#{viewport.messages.size} messages)")
       log.debug("compressed viewport:\n#{compressed_text}")
 
       result = @client.chat_with_tools(
-        messages,
+        llm_messages,
         registry: build_registry(viewport),
         session_id: nil,
         system: system
@@ -118,7 +100,7 @@ module Mneme
 
     private
 
-    # Builds the compressed viewport starting from the session's boundary event.
+    # Builds the compressed viewport starting from the session's boundary message.
     #
     # @return [Mneme::CompressedViewport]
     def build_compressed_viewport
@@ -127,7 +109,7 @@ module Mneme
       CompressedViewport.new(
         @session,
         token_budget: token_budget,
-        from_event_id: @session.mneme_boundary_event_id
+        from_message_id: @session.mneme_boundary_message_id
       )
     end
 
@@ -150,59 +132,59 @@ module Mneme
     end
 
     # Builds the tool registry with session context for SaveSnapshot.
-    # Passes the event range from the viewport so the snapshot records
-    # which events it covers.
+    # 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_events = viewport.events
+      viewport_messages = viewport.messages
       registry = ::Tools::Registry.new(context: {
         main_session: @session,
-        from_event_id: viewport_events.first&.id,
-        to_event_id: viewport_events.last&.id
+        from_message_id: viewport_messages.first&.id,
+        to_message_id: viewport_messages.last&.id
       })
       TOOLS.each { |tool| registry.register(tool) }
       registry
     end
 
-    # Advances the terminal event pointer after Mneme completes.
+    # Advances the terminal message pointer after Mneme completes.
     # 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 it to the last conversation event in the viewport, ensuring
-    # the boundary is always a message/think event, never a tool_call/tool_response.
+    # Sets it to the last conversation message in the viewport, ensuring
+    # the boundary is always a message/think message, never a tool_call/tool_response.
     # Also updates the snapshot range pointers.
     #
     # @param viewport [Mneme::CompressedViewport]
     def advance_boundary(viewport)
-      viewport_events = viewport.events
-      return if viewport_events.empty?
+      viewport_messages = viewport.messages
+      return if viewport_messages.empty?
 
-      new_boundary = viewport_events.reverse_each.find { |event| conversation_or_think?(event) }
+      new_boundary = viewport_messages.reverse_each.find { |message| conversation_or_think?(message) }
       return unless new_boundary
 
       boundary_id = new_boundary.id
-      updates = {mneme_boundary_event_id: boundary_id}
+      updates = {mneme_boundary_message_id: boundary_id}
 
-      updates[:mneme_snapshot_first_event_id] = viewport_events.first.id if @session.mneme_snapshot_first_event_id.nil?
-      updates[:mneme_snapshot_last_event_id] = viewport_events.last.id
+      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
 
       @session.update_columns(updates)
-      log.debug("session=#{@session.id} — boundary advanced to event #{boundary_id}")
+      log.debug("session=#{@session.id} — boundary advanced to message #{boundary_id}")
     end
 
-    # Delegates to {Event#conversation_or_think?} — single source of truth
-    # for which events Mneme treats as conversation boundaries.
+    # Delegates to {Message#conversation_or_think?} — single source of truth
+    # for which messages Mneme treats as conversation boundaries.
     #
     # @return [Boolean]
-    def conversation_or_think?(event)
-      event.conversation_or_think?
+    def conversation_or_think?(message)
+      message.conversation_or_think?
     end
 
     # Builds the active goals section for Mneme's context so it knows
-    # what Goals exist, which events are already pinned, and can reference
+    # 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
@@ -231,21 +213,21 @@ module Mneme
       parts.join("\n")
     end
 
-    # Lists already-pinned event IDs so Mneme avoids redundant pinning.
+    # 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_events.includes(:goals).order(:event_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")
     end
 
-    # @param pin [PinnedEvent] pin with preloaded goals
+    # @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(", ")
-      "  event #{pin.event_id} → goals [#{goal_ids}]"
+      "  message #{pin.message_id} → goals [#{goal_ids}]"
     end
 
     # @return [Logger]

data/lib/mneme/search.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Mneme
-  # Full-text search over event history using SQLite FTS5.
-  # Covers user messages, agent messages, and think events across all sessions.
+  # Full-text search over message history using SQLite FTS5.
+  # Covers user messages, agent messages, and think messages across all sessions.
   #
   # The interface is intentionally abstract — callers receive {Result} structs
   # and never touch FTS5 directly. A future semantic search backend (embeddings,
@@ -10,21 +10,21 @@ module Mneme
   #
   # @example Search across all sessions
   #   results = Mneme::Search.query("authentication flow")
-  #   results.each { |r| puts "event #{r.event_id}: #{r.snippet}" }
+  #   results.each { |r| puts "message #{r.message_id}: #{r.snippet}" }
   #
   # @example Search within a single session
   #   results = Mneme::Search.query("OAuth config", session_id: 42)
   class Search
     # A single search result with enough context for display and drill-down.
     #
-    # @!attribute event_id [Integer] the event's database ID
-    # @!attribute session_id [Integer] the session owning this event
+    # @!attribute message_id [Integer] the message's database ID
+    # @!attribute session_id [Integer] the session owning this message
     # @!attribute snippet [String] highlighted excerpt from the matching content
     # @!attribute rank [Float] FTS5 relevance score (lower = more relevant)
-    # @!attribute event_type [String] friendly label: human, anima, system, or thought
-    Result = Struct.new(:event_id, :session_id, :snippet, :rank, :event_type, keyword_init: true)
+    # @!attribute message_type [String] friendly label: human, anima, system, or thought
+    Result = Struct.new(:message_id, :session_id, :snippet, :rank, :message_type, keyword_init: true)
 
-    # Searches event history for the given terms.
+    # Searches message history for the given terms.
     #
     # @param terms [String] search query (FTS5 syntax: words, phrases, OR/AND/NOT)
     # @param session_id [Integer, nil] scope to a specific session (nil = all sessions)
@@ -52,7 +52,7 @@ module Mneme
     private
 
     # Executes the FTS5 MATCH query with optional session scoping.
-    # Joins back to events table for session_id and event_type.
+    # Joins back to messages table for session_id and message_type.
     #
     # @return [Array<Hash>] raw database rows
     def execute_fts_query
@@ -66,29 +66,29 @@ module Mneme
     end
 
     # FTS5 query across all sessions.
-    # Contentless FTS5 can't use snippet() — extract content from events directly.
+    # Contentless FTS5 can't use snippet() — extract content from messages directly.
     #
     # Ranking blends BM25 relevance with recency: rank is negative (more
-    # negative = better match), so dividing by a factor > 1 for older events
+    # negative = better match), so dividing by a factor > 1 for older messages
     # moves them closer to zero (less relevant). At decay 0.3, a one-year-old
     # result needs ~30% better keyword relevance to beat an identical match
     # from today.
     def global_sql
       <<~SQL
         SELECT
-          e.id AS event_id,
-          e.session_id,
-          e.event_type,
+          m.id AS message_id,
+          m.session_id,
+          m.message_type,
           CASE
-            WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
-              THEN substr(json_extract(e.payload, '$.content'), 1, 300)
-            WHEN e.event_type = 'tool_call'
-              THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
+            WHEN m.message_type IN ('user_message', 'agent_message', 'system_message')
+              THEN substr(json_extract(m.payload, '$.content'), 1, 300)
+            WHEN m.message_type = 'tool_call'
+              THEN substr(json_extract(m.payload, '$.tool_input.thoughts'), 1, 300)
           END AS snippet,
-          rank / (1.0 + ? * (julianday('now') - julianday(e.created_at)) / 365.0) AS rank
-        FROM events_fts
-        JOIN events e ON e.id = events_fts.rowid
-        WHERE events_fts MATCH ?
+          rank / (1.0 + ? * (julianday('now') - julianday(m.created_at)) / 365.0) AS rank
+        FROM messages_fts
+        JOIN messages m ON m.id = messages_fts.rowid
+        WHERE messages_fts MATCH ?
         ORDER BY rank
         LIMIT ?
       SQL
@@ -98,26 +98,26 @@ module Mneme
     def scoped_sql
       <<~SQL
         SELECT
-          e.id AS event_id,
-          e.session_id,
-          e.event_type,
+          m.id AS message_id,
+          m.session_id,
+          m.message_type,
           CASE
-            WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
-              THEN substr(json_extract(e.payload, '$.content'), 1, 300)
-            WHEN e.event_type = 'tool_call'
-              THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
+            WHEN m.message_type IN ('user_message', 'agent_message', 'system_message')
+              THEN substr(json_extract(m.payload, '$.content'), 1, 300)
+            WHEN m.message_type = 'tool_call'
+              THEN substr(json_extract(m.payload, '$.tool_input.thoughts'), 1, 300)
           END AS snippet,
-          rank / (1.0 + ? * (julianday('now') - julianday(e.created_at)) / 365.0) AS rank
-        FROM events_fts
-        JOIN events e ON e.id = events_fts.rowid
-        WHERE events_fts MATCH ?
-          AND e.session_id = ?
+          rank / (1.0 + ? * (julianday('now') - julianday(m.created_at)) / 365.0) AS rank
+        FROM messages_fts
+        JOIN messages m ON m.id = messages_fts.rowid
+        WHERE messages_fts MATCH ?
+          AND m.session_id = ?
         ORDER BY rank
         LIMIT ?
       SQL
     end
 
-    FRIENDLY_EVENT_TYPES = {
+    FRIENDLY_MESSAGE_TYPES = {
       "user_message" => "human",
       "agent_message" => "anima",
       "system_message" => "system",
@@ -129,13 +129,13 @@ module Mneme
     # @param row [Hash]
     # @return [Result]
     def build_result(row)
-      raw_type = row["event_type"]
+      raw_type = row["message_type"]
       Result.new(
-        event_id: row["event_id"],
+        message_id: row["message_id"],
         session_id: row["session_id"],
         snippet: row["snippet"],
         rank: row["rank"],
-        event_type: FRIENDLY_EVENT_TYPES.fetch(raw_type, raw_type)
+        message_type: FRIENDLY_MESSAGE_TYPES.fetch(raw_type, raw_type)
       )
     end
 

data/lib/mneme/tools/attach_messages_to_goals.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Pins critical messages to active Goals so they survive viewport eviction.
+    # Mneme calls this when it sees important messages (user instructions, key
+    # decisions, critical corrections) approaching the eviction zone.
+    #
+    # Messages are pinned via a many-to-many join: one message can be attached
+    # to multiple Goals. When all referencing Goals complete, the pin is
+    # automatically released (reference-counted cleanup in {Goal#release_orphaned_pins!}).
+    class AttachMessagesToGoals < ::Tools::Base
+      def self.tool_name = "attach_messages_to_goals"
+
+      def self.description = "Pin critical messages to goals so they survive viewport eviction."
+
+      def self.input_schema
+        {
+          type: "object",
+          properties: {
+            message_ids: {
+              type: "array",
+              items: {type: "integer"}
+            },
+            goal_ids: {
+              type: "array",
+              items: {type: "integer"}
+            }
+          },
+          required: %w[message_ids goal_ids]
+        }
+      end
+
+      # @param main_session [Session] the session being observed
+      def initialize(main_session:, **)
+        @session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "message_ids" and "goal_ids"
+      # @return [String] confirmation with link count, or error description
+      def execute(input)
+        message_ids = Array(input["message_ids"]).map(&:to_i).uniq
+        goal_ids = Array(input["goal_ids"]).map(&:to_i).uniq
+
+        return "Error: message_ids cannot be empty" if message_ids.empty?
+        return "Error: goal_ids cannot be empty" if goal_ids.empty?
+
+        messages = @session.messages.where(id: message_ids)
+        all_goals = @session.goals
+        goals = all_goals.active.where(id: goal_ids)
+
+        missing_messages = message_ids - messages.pluck(:id)
+        inactive_goal_ids = goal_ids - goals.pluck(:id)
+
+        errors = []
+        errors << "Messages not found: #{missing_messages.join(", ")}" if missing_messages.any?
+
+        if inactive_goal_ids.any?
+          completed_ids = all_goals.completed.where(id: inactive_goal_ids).pluck(:id)
+          not_found_ids = inactive_goal_ids - completed_ids
+          errors << "Goals already completed: #{completed_ids.join(", ")}" if completed_ids.any?
+          errors << "Goals not found: #{not_found_ids.join(", ")}" if not_found_ids.any?
+        end
+
+        return "Error: #{errors.join("; ")}" if errors.any?
+
+        attached = attach(messages, goals)
+        "Pinned #{attached} message-goal links"
+      end
+
+      private
+
+      def attach(messages, goals)
+        messages.sum do |message|
+          pinned = find_or_create_pinned_message(message)
+          link_to_goals(pinned, goals)
+        end
+      end
+
+      def link_to_goals(pinned, goals)
+        goals.each { |goal| GoalPinnedMessage.find_or_create_by!(goal: goal, pinned_message: pinned) }
+        goals.size
+      end
+
+      def find_or_create_pinned_message(message)
+        PinnedMessage.find_or_create_by!(message: message) do |pm|
+          pm.display_text = truncate_message_content(message)
+        end
+      end
+
+      def truncate_message_content(message)
+        content = message.payload&.dig("content").to_s.strip
+        content = "message #{message.id}" if content.empty?
+
+        if content.length > PinnedMessage::MAX_DISPLAY_TEXT_LENGTH
+          content[0, PinnedMessage::MAX_DISPLAY_TEXT_LENGTH - 1] + "…"
+        else
+          content
+        end
+      end
+    end
+  end
+end

data/lib/mneme/tools/everything_ok.rb

@@ -8,9 +8,7 @@ module Mneme
     class EverythingOk < ::Tools::Base
       def self.tool_name = "everything_ok"
 
-      def self.description = "Signal that no snapshot is needed. " \
-        "Call this when the eviction zone contains only mechanical " \
-        "activity (tool calls) with no meaningful conversation to summarize."
+      def self.description = "Nothing else worth remembering."
 
       def self.input_schema
         {type: "object", properties: {}, required: []}

data/lib/mneme/tools/save_snapshot.rb

@@ -12,10 +12,7 @@ module Mneme
     class SaveSnapshot < ::Tools::Base
       def self.tool_name = "save_snapshot"
 
-      def self.description = "Save a summary of the conversation context " \
-        "that is about to leave the viewport. Write a concise summary " \
-        "capturing key decisions, topics discussed, and important context. " \
-        "Focus on WHAT was decided and WHY, not mechanical details."
+      def self.description = "Summarize what's leaving the viewport."
 
       def self.input_schema
         {
@@ -23,8 +20,7 @@ module Mneme
           properties: {
             text: {
               type: "string",
-              description: "The summary text. Be concise but preserve key decisions, " \
-                "goals discussed, and important context. Max #{Anima::Settings.mneme_max_tokens} tokens."
+              maxLength: Anima::Settings.mneme_max_tokens * Message::BYTES_PER_TOKEN
             }
           },
           required: %w[text]
@@ -32,13 +28,13 @@ module Mneme
       end
 
       # @param main_session [Session] the session being observed
-      # @param from_event_id [Integer] first event ID covered by this snapshot
-      # @param to_event_id [Integer] last event ID covered by this snapshot
-      # @param level [Integer] compression level (1 = from events, 2 = from L1 snapshots)
-      def initialize(main_session:, from_event_id:, to_event_id:, level: 1, **)
+      # @param from_message_id [Integer] first message ID covered by this snapshot
+      # @param to_message_id [Integer] last message ID covered by this snapshot
+      # @param level [Integer] compression level (1 = from messages, 2 = from L1 snapshots)
+      def initialize(main_session:, from_message_id:, to_message_id:, level: 1, **)
         @main_session = main_session
-        @from_event_id = from_event_id
-        @to_event_id = to_event_id
+        @from_message_id = from_message_id
+        @to_message_id = to_message_id
         @level = level
       end
 
@@ -48,20 +44,20 @@ module Mneme
 
         snapshot = @main_session.snapshots.create!(
           text: text,
-          from_event_id: @from_event_id,
-          to_event_id: @to_event_id,
+          from_message_id: @from_message_id,
+          to_message_id: @to_message_id,
           level: @level,
           token_count: estimate_tokens(text)
         )
 
-        "Snapshot saved (id: #{snapshot.id}, events #{@from_event_id}..#{@to_event_id})"
+        "Snapshot saved (id: #{snapshot.id}, messages #{@from_message_id}..#{@to_message_id})"
       end
 
       private
 
       # @return [Integer] estimated token count for the summary text
       def estimate_tokens(text)
-        [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+        [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
       end
     end
   end