anima-core 1.0.2 → 1.1.1

data/app/models/session.rb

@@ -11,10 +11,14 @@ class Session < ApplicationRecord
 
   VIEW_MODES = %w[basic verbose debug].freeze
 
+  attribute :view_mode, :string, default: -> { Anima::Settings.default_view_mode }
+
   serialize :granted_tools, coder: JSON
 
   has_many :events, -> { order(:id) }, dependent: :destroy
   has_many :goals, dependent: :destroy
+  has_many :snapshots, dependent: :destroy
+  has_many :pinned_events, through: :events
 
   belongs_to :parent_session, class_name: "Session", optional: true
   has_many :child_sessions, class_name: "Session", foreign_key: :parent_session_id, dependent: :destroy
@@ -42,6 +46,38 @@ class Session < ApplicationRecord
     parent_session_id.present?
   end
 
+  # Checks whether the Mneme terminal event has left the viewport and
+  # enqueues {MnemeJob} when it has. On the first event of a new session,
+  # initializes the boundary pointer.
+  #
+  # The terminal event is always a conversation event (user/agent message
+  # or think tool_call), never a bare tool_call/tool_response.
+  #
+  # @return [void]
+  def schedule_mneme!
+    return if sub_agent?
+
+    # Initialize boundary on first conversation event
+    if mneme_boundary_event_id.nil?
+      first_conversation = events.deliverable
+        .where(event_type: Event::CONVERSATION_TYPES)
+        .order(:id).first
+      first_conversation ||= events.deliverable
+        .where(event_type: "tool_call")
+        .detect { |e| e.payload["tool_name"] == Event::THINK_TOOL }
+
+      if first_conversation
+        update_column(:mneme_boundary_event_id, first_conversation.id)
+      end
+      return
+    end
+
+    # Check if boundary event has left the viewport
+    return if viewport_event_ids.include?(mneme_boundary_event_id)
+
+    MnemeJob.perform_later(id)
+  end
+
   # Enqueues the analytical brain to perform background maintenance on
   # this session. Currently handles session naming; future phases add
   # skill activation, goal tracking, and memory.
@@ -201,16 +237,105 @@ class Session < ApplicationRecord
   end
 
   # Builds the message array expected by the Anthropic Messages API.
-  # Includes user/agent messages and tool call/response events in
-  # Anthropic's wire format. Consecutive tool_call events are grouped
-  # into a single assistant message; consecutive tool_response events
-  # are grouped into a single user message with tool_result blocks.
-  # Pending messages are excluded — they haven't been delivered yet.
+  # Viewport layout (top to bottom):
+  #   [L2 snapshots] [L1 snapshots] [pinned events] [recalled memories] [sliding window events]
+  #
+  # Snapshots appear ONLY after their source events have evicted from
+  # the sliding window. L1 snapshots drop once covered by an L2 snapshot.
+  # Pinned events are critical context attached to active Goals — they
+  # survive eviction intact until their Goals complete.
+  # Recalled memories surface relevant older events (passive recall via goals).
+  # Each layer has a fixed token budget fraction — snapshots, pins, and recall
+  # consume viewport space, reducing the sliding window size.
+  #
+  # Sub-agent sessions skip snapshot/pin/recall injection (they inherit parent events directly).
   #
   # @param token_budget [Integer] maximum tokens to include (positive)
   # @return [Array<Hash>] Anthropic Messages API format
   def messages_for_llm(token_budget: Anima::Settings.token_budget)
-    assemble_messages(viewport_events(token_budget: token_budget, include_pending: false))
+    heal_orphaned_tool_calls!
+
+    sliding_budget = token_budget
+    snapshot_messages = []
+    pinned_messages = []
+    recall_messages = []
+
+    unless sub_agent?
+      l2_budget = (token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
+      l1_budget = (token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
+      pinned_budget = (token_budget * Anima::Settings.mneme_pinned_budget_fraction).to_i
+      recall_budget = (token_budget * Anima::Settings.recall_budget_fraction).to_i
+      sliding_budget = token_budget - l2_budget - l1_budget - pinned_budget - recall_budget
+    end
+
+    events = viewport_events(token_budget: sliding_budget, include_pending: false)
+
+    unless sub_agent?
+      first_event_id = events.first&.id
+      snapshot_messages = assemble_snapshot_messages(first_event_id, l2_budget: l2_budget, l1_budget: l1_budget)
+      pinned_messages = assemble_pinned_event_messages(first_event_id, budget: pinned_budget)
+      recall_messages = assemble_recall_messages(budget: recall_budget)
+    end
+
+    snapshot_messages + pinned_messages + recall_messages + assemble_messages(ensure_atomic_tool_pairs(events))
+  end
+
+  # Detects orphaned tool_call events (those without a matching tool_response
+  # and whose timeout has expired) and creates synthetic error responses.
+  # An orphaned tool_call permanently breaks the session because the
+  # Anthropic API rejects conversations where a tool_use block has no
+  # matching tool_result.
+  #
+  # Respects the per-call timeout stored in the tool_call event payload —
+  # a tool_call is only healed after its deadline has passed. This avoids
+  # prematurely healing long-running tools that the agent intentionally
+  # gave an extended timeout.
+  #
+  # @return [Integer] number of synthetic responses created
+  def heal_orphaned_tool_calls!
+    now_ns = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+    responded_ids = events.where(event_type: "tool_response").where.not(tool_use_id: nil).select(:tool_use_id)
+    unresponded = events.where(event_type: "tool_call").where.not(tool_use_id: nil)
+      .where.not(tool_use_id: responded_ids)
+
+    healed = 0
+    unresponded.find_each do |orphan|
+      timeout = orphan.payload["timeout"] || Anima::Settings.tool_timeout
+      deadline_ns = orphan.timestamp + (timeout * 1_000_000_000)
+      next if now_ns < deadline_ns
+
+      events.create!(
+        event_type: "tool_response",
+        payload: {
+          "type" => "tool_response",
+          "content" => "Tool execution timed out after #{timeout} seconds — no result was returned.",
+          "tool_name" => orphan.payload["tool_name"],
+          "tool_use_id" => orphan.tool_use_id,
+          "success" => false
+        },
+        tool_use_id: orphan.tool_use_id,
+        timestamp: now_ns
+      )
+      healed += 1
+    end
+    healed
+  end
+
+  # Creates a user message event record directly (bypasses EventBus+Persister).
+  # Used by {SessionChannel#speak} (immediate display), {AgentLoop#process},
+  # and sub-agent spawn tools ({Tools::SpawnSubagent}, {Tools::SpawnSpecialist})
+  # because the global {Events::Subscribers::Persister} skips non-pending user
+  # messages — these callers own the persistence lifecycle.
+  #
+  # @param content [String] user message text
+  # @return [Event] the persisted event record
+  def create_user_event(content)
+    now = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+    events.create!(
+      event_type: "user_message",
+      payload: {type: "user_message", content: content, session_id: id, timestamp: now},
+      timestamp: now
+    )
   end
 
   # Promotes all pending user messages to delivered status so they
@@ -227,6 +352,27 @@ class Session < ApplicationRecord
     promoted
   end
 
+  # Broadcasts child session list to all clients subscribed to the parent
+  # session. Called when a child session is created or its processing state
+  # changes so the HUD sub-agents section updates in real time.
+  #
+  # Queries children via FK directly (avoids loading the parent record) and
+  # selects only the columns needed for the HUD payload.
+  #
+  # @return [void]
+  def broadcast_children_update_to_parent
+    return unless parent_session_id
+
+    children = Session.where(parent_session_id: parent_session_id)
+      .order(:created_at)
+      .select(:id, :name, :processing)
+    ActionCable.server.broadcast("session_#{parent_session_id}", {
+      "action" => "children_updated",
+      "session_id" => parent_session_id,
+      "children" => children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+    })
+  end
+
   private
 
   # Reads the soul file — the agent's self-authored identity.
@@ -396,6 +542,256 @@ class Session < ApplicationRecord
     event_list
   end
 
+  # Ensures every tool_call in the event list has a matching tool_response
+  # (and vice versa) by removing unpaired events. The Anthropic API requires
+  # every tool_use block to have a tool_result — a missing partner causes
+  # a permanent API error. Token budget cutoffs can split pairs when the
+  # boundary falls between a tool_call and its tool_response.
+  #
+  # @param event_list [Array<Event>] chronologically ordered events
+  # @return [Array<Event>] events with unpaired tool events removed
+  def ensure_atomic_tool_pairs(event_list)
+    tool_events = event_list.select { |e| e.tool_use_id.present? }
+    return event_list if tool_events.empty?
+
+    paired = tool_events.group_by(&:tool_use_id)
+    complete_ids = paired.each_with_object(Set.new) do |(id, evts), set|
+      has_call = evts.any? { |e| e.event_type == "tool_call" }
+      has_response = evts.any? { |e| e.event_type == "tool_response" }
+      set << id if has_call && has_response
+    end
+
+    event_list.reject { |e| e.tool_use_id.present? && !complete_ids.include?(e.tool_use_id) }
+  end
+
+  # Selects visible snapshots and formats them as Anthropic messages.
+  # Snapshots are visible when their source events have fully evicted.
+  # L1 snapshots are excluded when covered by an L2 snapshot.
+  #
+  # @param first_event_id [Integer, nil] first event ID in the sliding window
+  # @param l2_budget [Integer] token budget for L2 snapshots
+  # @param l1_budget [Integer] token budget for L1 snapshots
+  # @return [Array<Hash>] Anthropic Messages API format
+  def assemble_snapshot_messages(first_event_id, l2_budget:, l1_budget:)
+    return [] unless first_event_id
+
+    l2_messages = select_snapshots_within_budget(
+      snapshots.for_level(2).source_events_evicted(first_event_id).chronological,
+      budget: l2_budget
+    ).map { |snapshot| format_snapshot_message(snapshot, label: "long-term memory") }
+
+    l1_messages = select_snapshots_within_budget(
+      snapshots.for_level(1).not_covered_by_l2.source_events_evicted(first_event_id).chronological,
+      budget: l1_budget
+    ).map { |snapshot| format_snapshot_message(snapshot, label: "recent memory") }
+
+    l2_messages + l1_messages
+  end
+
+  # Walks snapshots chronologically, selecting until the token budget is exhausted.
+  # Always includes at least one snapshot even if it exceeds the budget, so the
+  # agent never loses all memory context.
+  #
+  # @param scope [ActiveRecord::Relation] snapshot scope to select from
+  # @param budget [Integer] maximum tokens to include
+  # @return [Array<Snapshot>]
+  def select_snapshots_within_budget(scope, budget:)
+    selected = []
+    remaining = budget
+
+    scope.each do |snapshot|
+      cost = snapshot.token_cost
+      break if cost > remaining && selected.any?
+
+      selected << snapshot
+      remaining -= cost
+    end
+
+    selected
+  end
+
+  # Formats a snapshot as an Anthropic user message with a memory label prefix.
+  #
+  # @param snapshot [Snapshot]
+  # @param label [String] human-readable label (e.g. "recent memory", "long-term memory")
+  # @return [Hash] Anthropic message format
+  def format_snapshot_message(snapshot, label:)
+    {role: "user", content: "[#{label}]\n#{snapshot.text}"}
+  end
+
+  # Assembles pinned events as a Goals section message for the viewport.
+  # Only includes pinned events whose source event has evicted from the
+  # sliding window (same rule as snapshots — no duplication with live events).
+  #
+  # Deduplication: the first Goal referencing an event shows its truncated
+  # display_text; subsequent Goals show a bare `event N` ID to save tokens.
+  #
+  # @param first_event_id [Integer, nil] first event ID in the sliding window
+  # @param budget [Integer] token budget for pinned events
+  # @return [Array<Hash>] Anthropic Messages API format (0 or 1 messages)
+  def assemble_pinned_event_messages(first_event_id, budget:)
+    return [] unless first_event_id
+
+    pins = pinned_events
+      .includes(:event, :goals)
+      .where("pinned_events.event_id < ?", first_event_id)
+      .order("pinned_events.event_id")
+
+    return [] if pins.empty?
+
+    selected = select_pins_within_budget(pins, budget)
+    return [] if selected.empty?
+
+    text = render_pinned_events_section(selected)
+    [{role: "user", content: "[pinned events]\n#{text}"}]
+  end
+
+  # Walks pinned events chronologically, selecting until the token budget
+  # is exhausted. Always includes at least one pin.
+  #
+  # @param pins [Array<PinnedEvent>]
+  # @param budget [Integer]
+  # @return [Array<PinnedEvent>]
+  def select_pins_within_budget(pins, budget)
+    selected = []
+    remaining = budget
+
+    pins.each do |pin|
+      cost = pin.token_cost
+      break if cost > remaining && selected.any?
+
+      selected << pin
+      remaining -= cost
+    end
+
+    selected
+  end
+
+  # Renders the pinned events section grouped by Goal.
+  # First Goal referencing a pin shows truncated text; subsequent Goals
+  # show bare `event N` ID to avoid token-expensive repetition.
+  #
+  # @param pins [Array<PinnedEvent>] selected pins with preloaded goals
+  # @return [String] formatted section text
+  def render_pinned_events_section(pins)
+    goal_pins = group_pins_by_active_goal(pins)
+
+    shown_events = Set.new
+    goal_pins.map { |goal, pin_list|
+      render_goal_pins(goal, pin_list, shown_events)
+    }.join("\n\n")
+  end
+
+  # Groups pins by their active Goals so the viewport renders
+  # one headed section per Goal.
+  #
+  # @param pins [Array<PinnedEvent>] pins with preloaded goals
+  # @return [Hash{Goal => Array<PinnedEvent>}]
+  def group_pins_by_active_goal(pins)
+    pairs = pins.flat_map { |pin| active_goal_pin_pairs(pin) }
+    pairs.group_by(&:first).transform_values { |group| group.map(&:last) }
+  end
+
+  # Expands a single pin into [goal, pin] pairs for each active Goal
+  # referencing it. Uses in-memory filter on preloaded goals.
+  #
+  # @param pin [PinnedEvent]
+  # @return [Array<Array(Goal, PinnedEvent)>]
+  def active_goal_pin_pairs(pin)
+    pin.goals.select(&:active?).map { |goal| [goal, pin] }
+  end
+
+  # Renders one Goal's pinned events as a headed list.
+  #
+  # @param goal [Goal]
+  # @param pin_list [Array<PinnedEvent>]
+  # @param shown_events [Set<Integer>] tracks already-rendered event IDs for dedup
+  # @return [String]
+  def render_goal_pins(goal, pin_list, shown_events)
+    lines = ["📌 #{goal.description} (id: #{goal.id})"]
+    pin_list.each { |pin| lines << format_pin_line(pin, shown_events) }
+    lines.join("\n")
+  end
+
+  # Formats a single pin line with deduplication: first occurrence shows
+  # truncated text, subsequent occurrences show bare event ID only.
+  #
+  # @param pin [PinnedEvent]
+  # @param shown_events [Set<Integer>]
+  # @return [String]
+  def format_pin_line(pin, shown_events)
+    event_id = pin.event_id
+    if shown_events.add?(event_id)
+      "  event #{event_id}: #{pin.display_text}"
+    else
+      "  event #{event_id}"
+    end
+  end
+
+  # Assembles recalled memory messages from passive recall results.
+  # Recalled events are fetched by ID and formatted as compact snippets
+  # with session and event context for drill-down via the remember tool.
+  #
+  # @param budget [Integer] token budget for recall messages
+  # @return [Array<Hash>] Anthropic Messages API format
+  def assemble_recall_messages(budget:)
+    return [] if recalled_event_ids.blank?
+
+    recalled_events = Event.where(id: recalled_event_ids)
+      .includes(:session)
+      .index_by(&:id)
+
+    snippets = []
+    remaining = budget
+
+    recalled_event_ids.each do |eid|
+      event = recalled_events[eid]
+      next unless event
+
+      text = format_recall_snippet(event)
+      cost = [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+      break if cost > remaining && snippets.any?
+
+      snippets << text
+      remaining -= cost
+    end
+
+    return [] if snippets.empty?
+
+    [{role: "user", content: "[associative recall]\n#{snippets.join("\n\n")}"}]
+  end
+
+  # Formats a recalled event as a compact snippet with enough context
+  # for the agent to decide whether to drill down with the remember tool.
+  #
+  # @param event [Event] the recalled event
+  # @return [String] formatted snippet
+  def format_recall_snippet(event)
+    session_label = event.session.name || "session ##{event.session_id}"
+    content = extract_event_content(event).to_s.truncate(Anima::Settings.recall_max_snippet_tokens * Event::BYTES_PER_TOKEN)
+    "event #{event.id} (#{session_label}): #{content}"
+  end
+
+  # Extracts readable content from an event's payload.
+  #
+  # @param event [Event]
+  # @return [String]
+  def extract_event_content(event)
+    data = event.payload
+    case event.event_type
+    when "user_message", "agent_message", "system_message"
+      data["content"]
+    when "tool_call"
+      if data["tool_name"] == Event::THINK_TOOL
+        data.dig("tool_input", "thoughts")
+      else
+        "#{data["tool_name"]}(…)"
+      end
+    else
+      data["content"]
+    end
+  end
+
   # Converts a chronological list of events into Anthropic wire-format messages.
   # Prepends a compact timestamp to each user message for LLM time awareness.
   # Groups consecutive tool_call events into one assistant message and

data/app/models/snapshot.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# A persisted summary of conversation context created by Mneme before
+# events evict from the viewport. Snapshots capture the "gist" of what
+# happened so the agent retains awareness of past context.
+#
+# Level 1 snapshots are created from raw events (messages + thinks).
+# Level 2 snapshots compress multiple Level 1 snapshots (days/weeks scale).
+# Both levels use the same event ID range tracking — an L2 snapshot's range
+# is the union of its constituent L1 snapshots.
+#
+# @!attribute text
+#   @return [String] the summary text generated by Mneme
+# @!attribute from_event_id
+#   @return [Integer] first event ID covered by this snapshot
+# @!attribute to_event_id
+#   @return [Integer] last event ID covered by this snapshot
+# @!attribute level
+#   @return [Integer] compression level (1 = from raw events, 2 = from L1 snapshots)
+# @!attribute token_count
+#   @return [Integer] cached token count of the summary text
+class Snapshot < ApplicationRecord
+  belongs_to :session
+
+  # 32KB — generous upper bound (~8K tokens). The LLM tool description advises
+  # a tighter limit (mneme_max_tokens), but this hard cap prevents unbounded storage.
+  MAX_TEXT_BYTES = 32_768
+
+  validates :text, presence: true, length: {maximum: MAX_TEXT_BYTES}
+  validates :from_event_id, presence: true
+  validates :to_event_id, presence: true
+  validates :level, presence: true, numericality: {greater_than: 0}
+  validates :token_count, numericality: {greater_than_or_equal_to: 0}, allow_nil: true
+  validate :from_event_id_not_after_to_event_id
+
+  scope :for_level, ->(level) { where(level: level) }
+  scope :chronological, -> { order(:from_event_id) }
+
+  # L1 snapshots whose event range is NOT fully contained within any L2 snapshot.
+  # Used to determine which L1 snapshots are still "live" in the viewport.
+  scope :not_covered_by_l2, -> {
+    where.not(
+      "EXISTS (SELECT 1 FROM snapshots l2 " \
+      "WHERE l2.session_id = snapshots.session_id " \
+      "AND l2.level = 2 " \
+      "AND l2.from_event_id <= snapshots.from_event_id " \
+      "AND l2.to_event_id >= snapshots.to_event_id)"
+    )
+  }
+
+  # Snapshots whose source events have fully evicted from the sliding window.
+  # A snapshot is visible when its entire event range precedes the first
+  # event currently in the viewport.
+  #
+  # @param first_event_id [Integer] the first event ID in the sliding window
+  scope :source_events_evicted, ->(first_event_id) {
+    where("to_event_id < ?", first_event_id)
+  }
+
+  # @return [Integer] token cost, using cached count or heuristic estimate
+  def token_cost
+    token_count.positive? ? token_count : estimate_tokens
+  end
+
+  private
+
+  def from_event_id_not_after_to_event_id
+    return unless from_event_id && to_event_id
+    errors.add(:from_event_id, "must be <= to_event_id") if from_event_id > to_event_id
+  end
+
+  # @return [Integer] estimated token count (at least 1)
+  def estimate_tokens
+    [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+  end
+end

data/bin/jobs

@@ -3,4 +3,9 @@
 require_relative "../config/environment"
 require "solid_queue/cli"
 
+# Run all Solid Queue components (worker, dispatcher, scheduler) as threads
+# in a single process. Fork mode spawns child processes that can outlive
+# the supervisor and run stale code after gem updates (#275).
+ENV["SOLID_QUEUE_SUPERVISOR_MODE"] = "async"
+
 SolidQueue::Cli.start(ARGV)

data/config/initializers/event_subscribers.rb

@@ -4,7 +4,16 @@
 # Subscribers registered here receive all events regardless of which
 # process emitted them (brain server, background job, etc.).
 Rails.application.config.after_initialize do
-  # Global persister handles events from all sessions (brain server, background jobs).
-  # Skipped in test — specs manage their own persisters for isolation.
-  Events::Bus.subscribe(Events::Subscribers::Persister.new) unless Rails.env.test?
+  unless Rails.env.test?
+    # Global persister handles events from all sessions (brain server, background jobs).
+    # Skips non-pending user messages — those are persisted by their callers
+    # (SessionChannel#speak for idle sessions, AgentLoop#process for direct usage).
+    Events::Bus.subscribe(Events::Subscribers::Persister.new)
+
+    # Bridges transient events (e.g. BounceBack) to ActionCable for client delivery.
+    Events::Bus.subscribe(Events::Subscribers::TransientBroadcaster.new)
+
+    # Routes text messages between parent and sub-agent sessions via @mentions.
+    Events::Bus.subscribe(Events::Subscribers::SubagentMessageRouter.new)
+  end
 end

data/config/initializers/fts5_schema_dump.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Skip FTS5 virtual tables during Ruby schema dump.
+# Rails' schema dumper can't express contentless FTS5 tables — the
+# migration handles creation. The schema.rb omits the virtual table,
+# and db:prepare runs pending migrations to recreate it.
+ActiveSupport.on_load(:active_record) do
+  require "active_record/connection_adapters/sqlite3/schema_dumper"
+
+  ActiveRecord::ConnectionAdapters::SQLite3::SchemaDumper.prepend(Module.new do
+    private
+
+    def virtual_tables(stream)
+      # Intentionally empty — FTS5 tables are managed by migrations.
+      # The default implementation crashes on contentless FTS5 arguments.
+    end
+  end)
+rescue LoadError
+  # Not using SQLite3 adapter — nothing to patch.
+  nil
+end

data/config/queue.yml

@@ -5,7 +5,6 @@ default: &default
   workers:
     - queues: "*"
       threads: 3
-      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
       polling_interval: 0.1
 
 development:

data/db/migrate/20260321080000_create_mneme_schema.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Adds Mneme memory department infrastructure:
+# - Terminal event tracking on sessions for viewport eviction detection
+# - Snapshot pointers for tracking what Mneme has already summarized
+# - Snapshots table for persisted summaries of evicted conversation context
+class CreateMnemeSchema < ActiveRecord::Migration[8.1]
+  def change
+    # Terminal event trigger: the event ID that marks Mneme's boundary.
+    # When this event leaves the viewport, Mneme fires.
+    add_column :sessions, :mneme_boundary_event_id, :integer
+
+    # Snapshot range pointers: track which events Mneme has summarized.
+    add_column :sessions, :mneme_snapshot_first_event_id, :integer
+    add_column :sessions, :mneme_snapshot_last_event_id, :integer
+
+    create_table :snapshots do |t|
+      t.references :session, null: false, foreign_key: true
+      t.text :text, null: false
+      t.integer :from_event_id, null: false
+      t.integer :to_event_id, null: false
+      t.integer :level, null: false, default: 1
+      t.integer :token_count, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :snapshots, [:session_id, :level]
+    add_index :snapshots, [:session_id, :from_event_id, :to_event_id],
+      name: "index_snapshots_on_session_and_event_range"
+  end
+end

data/db/migrate/20260321120000_create_pinned_events.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Goal-scoped event pinning: Mneme pins critical events to Goals via a
+# many-to-many relationship. Pinned events float above the sliding window,
+# protected from viewport eviction. When a Goal completes, events attached
+# exclusively to it are automatically released (reference counting).
+class CreatePinnedEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :pinned_events do |t|
+      t.references :event, null: false, foreign_key: true, index: {unique: true}
+      t.text :display_text, null: false
+
+      t.timestamps
+    end
+
+    create_table :goal_pinned_events do |t|
+      t.references :goal, null: false, foreign_key: true
+      t.references :pinned_event, null: false, foreign_key: true
+
+      t.timestamps
+    end
+
+    # One event pinned to a goal at most once.
+    # (t.references already creates individual indexes on goal_id and pinned_event_id)
+    add_index :goal_pinned_events, [:goal_id, :pinned_event_id], unique: true
+  end
+end