anima-core 1.3.0 → 1.5.0

data/lib/mneme/runner.rb

@@ -1,198 +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.
+      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.
 
-      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.
+      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.
 
-      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
+      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.
 
-    # @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
+      If the eviction zone holds only mechanical activity — tool calls, no conversation — call everything_ok and let it fall off without a snapshot.
 
-      llm_messages = build_messages(compressed_text)
-      system = SYSTEM_PROMPT
-
-      log.info("session=#{sid} — running Mneme (#{viewport.messages.size} messages)")
-      log.debug("compressed viewport:\n#{compressed_text}")
-
-      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
 
-    # 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
+    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
+
+      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 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 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_messages = viewport.messages
-      return if viewport_messages.empty?
-
-      new_boundary = viewport_messages.reverse_each.find { |message| conversation_or_think?(message) }
-      return unless new_boundary
-
-      boundary_id = new_boundary.id
-      updates = {mneme_boundary_message_id: boundary_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 message #{boundary_id}")
+    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)
+        .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
+
+    # 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
 
-    # 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?
+    # 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
 
-    # 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
+    # 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
+
+      lines << flush_tool_count(tool_count) if tool_count > 0
+      lines.join("\n")
+    end
+
+    def flush_tool_count(count)
+      "[#{count} #{(count == 1) ? "tool" : "tools"} called]"
+    end
+
+    # 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"
@@ -200,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]" : "[ ]"
@@ -213,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

data/lib/mneme/search.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 module Mneme
-  # Full-text search over message history using SQLite FTS5.
-  # Covers user messages, agent messages, and think messages across all sessions.
+  # Full-text search over long-term memory — the message history outside
+  # the caller's current viewport. Covers user messages, agent messages,
+  # and think messages across every session Anima has ever held.
   #
   # The interface is intentionally abstract — callers receive {Result} structs
   # and never touch FTS5 directly. A future semantic search backend (embeddings,
   # BM25 + re-ranking) can replace the implementation without changing callers.
   #
-  # @example Search across all sessions
-  #   results = Mneme::Search.query("authentication flow")
-  #   results.each { |r| puts "message #{r.message_id}: #{r.snippet}" }
+  # @example Mneme's recall muse searching for the main session
+  #   Mneme::Search.query("authentication flow", caller_session: session)
   #
-  # @example Search within a single session
-  #   results = Mneme::Search.query("OAuth config", session_id: 42)
+  # @example Aoide searching actively from her own session
+  #   Mneme::Search.query("OAuth config", caller_session: session)
   class Search
     # A single search result with enough context for display and drill-down.
     #
@@ -24,19 +24,27 @@ module Mneme
     # @!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 message history for the given terms.
+    # Searches long-term memory for the given terms.
+    #
+    # Excludes messages currently in the caller's viewport so a `LIMIT`-bounded
+    # search never burns its slots returning things the caller already has in
+    # front of them. A caller with no established Mneme boundary yet (fresh
+    # main session, sub-agent) treats the whole session as "in viewport" — none
+    # of its own messages surface.
     #
     # @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)
+    # @param caller_session [Session] the session doing the search — used to
+    #   exclude its own viewport from the results. Required; search always
+    #   happens from the perspective of a specific session.
     # @param limit [Integer] maximum results
     # @return [Array<Result>] ranked by relevance (best first)
-    def self.query(terms, session_id: nil, limit: Anima::Settings.recall_max_results)
-      new(terms, session_id: session_id, limit: limit).call
+    def self.query(terms, caller_session:, limit: Anima::Settings.recall_max_results)
+      new(terms, caller_session: caller_session, limit: limit).call
     end
 
-    def initialize(terms, session_id: nil, limit: 5)
+    def initialize(terms, caller_session:, limit: 5)
       @terms = sanitize_query(terms)
-      @session_id = session_id
+      @caller_session = caller_session
       @limit = limit
       @recency_decay = Anima::Settings.recall_recency_decay
     end
@@ -51,30 +59,29 @@ module Mneme
 
     private
 
-    # Executes the FTS5 MATCH query with optional session scoping.
-    # Joins back to messages table for session_id and message_type.
+    # Executes the FTS5 MATCH query with viewport exclusion for the caller.
     #
     # @return [Array<Hash>] raw database rows
     def execute_fts_query
-      sql = if @session_id
-        Arel.sql(scoped_sql, @recency_decay, @terms, @session_id, @limit)
-      else
-        Arel.sql(global_sql, @recency_decay, @terms, @limit)
-      end
-
-      connection.select_all(sql, "Mneme::Search").to_a
+      sql, binds = build_sql_and_binds
+      connection.select_all(Arel.sql(sql, *binds), "Mneme::Search").to_a
     end
 
-    # FTS5 query across all sessions.
-    # 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 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
+    # Builds the FTS5 SQL. Viewport exclusion depends on whether the caller's
+    # session has a Mneme boundary:
+    # * boundary set → exclude caller's messages at or above it (they're visible).
+    # * boundary nil → exclude the caller's whole session (no eviction has
+    #   happened yet, so everything is visible).
+    # Other sessions are always unfiltered — their IDs and boundaries mean
+    # nothing to the caller's context.
+    def build_sql_and_binds
+      binds = [@recency_decay, @terms]
+
+      viewport_clause, viewport_binds = caller_viewport_exclusion
+      binds.concat(viewport_binds)
+      binds << @limit
+
+      sql = <<~SQL
         SELECT
           m.id AS message_id,
           m.session_id,
@@ -89,32 +96,22 @@ module Mneme
         FROM messages_fts
         JOIN messages m ON m.id = messages_fts.rowid
         WHERE messages_fts MATCH ?
+          AND #{viewport_clause}
         ORDER BY rank
         LIMIT ?
       SQL
+
+      [sql, binds]
     end
 
-    # FTS5 query scoped to a specific session.
-    def scoped_sql
-      <<~SQL
-        SELECT
-          m.id AS message_id,
-          m.session_id,
-          m.message_type,
-          CASE
-            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(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
+    # Returns the SQL fragment + bind params that exclude the caller's viewport.
+    def caller_viewport_exclusion
+      boundary = @caller_session.mneme_boundary_message_id
+      if boundary
+        ["(m.session_id != ? OR m.id < ?)", [@caller_session.id, boundary]]
+      else
+        ["m.session_id != ?", [@caller_session.id]]
+      end
     end
 
     FRIENDLY_MESSAGE_TYPES = {
@@ -139,25 +136,70 @@ module Mneme
       )
     end
 
-    # Sanitizes user input for FTS5 MATCH safety.
-    # Strips special FTS5 operators that could cause syntax errors,
-    # keeps only alphanumeric words and quoted phrases.
+    # FTS5 logical-operator keywords callers may pass verbatim. Everything
+    # else is quote-wrapped, which is SQLite's recommended way to feed
+    # untrusted text to +MATCH+ — inside a quoted phrase the tokenizer
+    # treats +- : * ^ { } ( )+ and any future operator character as
+    # ordinary content, so hazards like +sub-agents+ (parsed as
+    # +sub NOT agents+ → +no such column: agents+) and +agents:foo+
+    # (parsed as a column filter) become literal phrases.
+    #
+    # Adding +NEAR+ or any new operator that a caller legitimately needs
+    # is a one-line change here; character-level blocklists would need to
+    # be re-audited against every FTS5 release.
+    #
+    # @see https://www.sqlite.org/fts5.html FTS5 query syntax
+    # @see https://www.mail-archive.com/sqlite-users@mailinglists.sqlite.org/msg118320.html
+    #   Dan Kennedy's canonical guidance on MATCH sanitization
+    FTS5_PASSTHROUGH_OPERATORS = Set.new(%w[AND OR NOT NEAR]).freeze
+    private_constant :FTS5_PASSTHROUGH_OPERATORS
+
+    # Sanitizes user input for FTS5 MATCH safety by quote-wrapping each
+    # token. Logical operators ({FTS5_PASSTHROUGH_OPERATORS}) pass through
+    # so callers that intentionally build +word1 OR word2+ queries still
+    # get boolean behavior.
+    #
+    # A query that collapses to operators only (e.g. user typed "and or
+    # not") has no operands and would trigger an FTS5 syntax error, so we
+    # return an empty string and let {#call} short-circuit via
+    # +@terms.blank?+.
     #
     # @param raw [String]
     # @return [String] safe FTS5 query
     def sanitize_query(raw)
       return "" unless raw
 
-      # Extract quoted phrases and individual words, drop FTS5 operators
-      tokens = raw.scan(/"[^"]+?"|\S+/).reject { |token| token.match?(/\A[*:^{}()]+\z/) }
-      tokens.filter_map { |token| sanitize_token(token) }.join(" ")
+      tokens = raw.scan(/"[^"]*"|\S+/).filter_map { |token| sanitize_token(token) }
+      return "" if tokens.all? { |t| FTS5_PASSTHROUGH_OPERATORS.include?(t) }
+
+      tokens.join(" ")
     end
 
+    # @param token [String] one whitespace-delimited chunk of user input
+    # @return [String, nil] nil when the token is empty after cleanup
     def sanitize_token(token)
-      return token if token.start_with?('"')
+      return token if FTS5_PASSTHROUGH_OPERATORS.include?(token)
+      return rewrap_phrase(token) if token.start_with?('"')
+
+      quote_as_phrase(token)
+    end
+
+    # Rebalances a user-supplied phrase so a stray or doubled quote can't
+    # leave the overall query syntactically broken.
+    #
+    # @param token [String] token starting with +"+
+    # @return [String, nil]
+    def rewrap_phrase(token)
+      inner = token.delete_prefix('"').delete_suffix('"').strip
+      inner.empty? ? nil : quote_as_phrase(inner)
+    end
+
+    # @param text [String] any token treated as literal content
+    # @return [String, nil]
+    def quote_as_phrase(text)
+      return nil if text.empty?
 
-      cleaned = token.gsub(/[^a-zA-Z0-9-]/, "")
-      cleaned.empty? ? nil : cleaned
+      %("#{text.gsub('"', '""')}")
     end
 
     def connection

data/lib/mneme/tools/nothing_to_surface.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Finish-line tool for {Mneme::RecallRunner}. The muse calls this when
+    # she's done her work — whether she surfaced memories or decided
+    # nothing was worth carrying forward. Having a single finish line makes
+    # every recall run explicit: silence is intentional, not a timeout.
+    #
+    # Mirror of {EverythingOk} for the eviction runner.
+    class NothingToSurface < ::Tools::Base
+      def self.tool_name = "nothing_to_surface"
+
+      def self.description = "Finish the recall run. Call this when you're done — whether you surfaced memories or decided nothing was worth surfacing right now. Silence is a valid answer when older memory wouldn't help."
+
+      def self.input_schema
+        {type: "object", properties: {}, required: []}
+      end
+
+      def execute(_input)
+        "Acknowledged."
+      end
+    end
+  end
+end

data/lib/mneme/tools/save_snapshot.rb

@@ -20,7 +20,7 @@ module Mneme
           properties: {
             text: {
               type: "string",
-              maxLength: Anima::Settings.mneme_max_tokens * Message::BYTES_PER_TOKEN
+              maxLength: Anima::Settings.mneme_max_tokens * TokenEstimation::BYTES_PER_TOKEN
             }
           },
           required: %w[text]
@@ -46,19 +46,11 @@ module Mneme
           text: text,
           from_message_id: @from_message_id,
           to_message_id: @to_message_id,
-          level: @level,
-          token_count: estimate_tokens(text)
+          level: @level
         )
 
         "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 / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
-      end
     end
   end
 end