samagotchi 0.40.0 → 0.41.0

data/lib/samagotchi/llm_context_command.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_override"
+require_relative "llm_context_strategy"
+require_relative "llm_context_edit"
+require_relative "llm_context_stale"
+
+module Samagotchi
+  # /llm-context, the session's own LLM context values
+  # (LLMContextOverride): with no arguments, the strategy, apply rule and
+  # budget the next turn runs under and where each came from (the session,
+  # models: <key>, a hosts entry, llm_context.*); with
+  # `strategy <layers|none>`, `apply <rule>` and `budget <N|off>` (any of
+  # them, in one line; `default` unsets one) it sets the session's own, and
+  # `reset` unsets them all. A change takes effect at the next turn's
+  # start (the REPL and the worker run it between turns), and the reply
+  # says what it costs: forget on or off changes the tool list and the
+  # system prompt (a full cache break); stale turned on stages the reads
+  # already superseded as one batch under the apply rule; a layer turned
+  # off sends its stubs whole again (the originals stay in the session, so
+  # turning it back on brings them back).
+  class LLMContextCommand
+    NAME = LLMContextOverride::COMMAND
+    USAGE = "usage: #{NAME} [strategy <none|stale,forget|default>] [apply <payoff|next_request|turn_end|default>] " \
+            "[budget <tokens|64k|off|default>] | #{NAME} reset".freeze
+    RESET = "reset"
+    FIELDS = LLMContextOverride::COMMAND_WORDS.invert.freeze
+
+    # @param engine [Engine] #llm_context_explained, #llm_context_override(=), #session
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /llm-context
+    # @return [Array(String, Boolean)] the reply and whether the values changed
+    # @raise [ArgumentError] a line that isn't one (its message and USAGE)
+    def run(args)
+      args = args.to_s.strip
+      return [listing(@engine.llm_context_explained), false] if args.empty?
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = @engine.llm_context_explained
+      updated = args.casecmp?(RESET) ? LLMContextOverride.new : LLMContextOverride.update(@engine.llm_context_override, words(args))
+      @engine.llm_context_override = updated
+      @save.call(session)
+      after = @engine.llm_context_explained
+      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true]
+    end
+
+    # The values, where each came from, and what the session sets itself.
+    def listing(explained)
+      return "llm context: can't be resolved for this model" unless explained
+
+      resolved = explained.resolved
+      own = @engine.llm_context_override
+      set = own ? LLMContextOverride::FIELDS.filter_map { |field| own_word(own, field) }.join("; ") : nil
+      [
+        "llm context: #{strategy_word(resolved)} (#{explained.strategy.where})",
+        "  apply:  #{resolved.apply} (#{explained.apply.where})",
+        "  budget: #{resolved.budget_tokens ? "#{resolved.budget_tokens} tokens" : "off"} (#{explained.budget_tokens.where})",
+        "  this session's own: #{set.to_s.empty? ? "none (follows the model, its host, then llm_context.*)" : set}"
+      ].join("\n")
+    end
+
+    private
+
+    # "strategy stale stale forget apply turn_end budget 64k" as fields
+    # and their words; a strategy takes the words up to the next field.
+    def words(args)
+      fields = {}
+      field = nil
+      args.split.each do |token|
+        if FIELDS.key?(token.downcase) && (field.nil? || fields[field])
+          field = FIELDS[token.downcase]
+          raise ArgumentError, "#{token} is given twice\n#{USAGE}" if fields.key?(field)
+
+          fields[field] = nil
+        elsif field.nil?
+          raise ArgumentError, "unknown #{NAME} word #{token}\n#{USAGE}"
+        elsif fields[field].nil? || field == :strategy
+          fields[field] = [fields[field], token].compact.join(" ")
+        else
+          raise ArgumentError, "#{FIELDS.key(field)} takes one value, not #{fields[field]} #{token}\n#{USAGE}"
+        end
+      end
+      missing = fields.find { |_field, word| word.nil? }
+      raise ArgumentError, "#{FIELDS.key(missing.first)} needs a value\n#{USAGE}" if missing
+
+      fields
+    end
+
+    def own_word(own, field)
+      word = LLMContextOverride.word(field, own.public_send(field))
+      word && "#{LLMContextOverride::COMMAND_WORDS[field]} #{word}"
+    end
+
+    def strategy_word(resolved) = resolved.active_layers.empty? ? "none" : resolved.active_layers.join(", ")
+
+    # What the change does from the next turn on.
+    def notes(session, before, after)
+      return [] unless before && after
+      return ["(no change to what the next turn runs under)"] if before.with(source: nil) == after.with(source: nil)
+
+      was = before.active_layers
+      now = after.active_layers
+      notes = ["From the next turn's start (a running turn keeps its own)."]
+      notes << forget_note(now.include?(:forget)) if was.include?(:forget) != now.include?(:forget)
+      notes << stale_note(session, after) if now.include?(:stale) && !was.include?(:stale)
+      (was - now).each do |layer|
+        count = applied_count(session.messages, layer)
+        next if count.zero?
+
+        notes << "#{layer}'s #{count} stub#{"s" if count != 1} go#{"es" if count == 1} out whole again (a cache break " \
+                 "from the first; the originals stay in the session, and turning #{layer} back on brings the stubs back)."
+      end
+      notes
+    end
+
+    def forget_note(on)
+      verb = on ? "joins" : "leaves"
+      note = "forget_outputs #{verb} the tool list and the system prompt#{" (and outputs show their ids)" if on}: " \
+             "the next request re-reads the whole prompt (a full cache break)."
+      on ? note : "#{note} Its past forget_outputs calls and their results stay in the history."
+    end
+
+    # How many past reads are already superseded, and when they go in.
+    def stale_note(session, resolved)
+      found = LLMContextStale.found(session.messages, root: session.working_directory.to_s,
+                                                      changes: resolved.stale_edits).size
+      return "stale: no past read is superseded yet." if found.zero?
+
+      when_in = case resolved.apply
+                when :next_request then "at the next request"
+                when :turn_end then "at the end of the next turn"
+                else "at the next request if what it frees pays for the re-read tail, else at the end of the next turn"
+                end
+      "stale: #{found} past read#{"s" if found != 1} already superseded go#{"es" if found == 1} in as one batch " \
+        "under apply #{resolved.apply}: #{when_in}."
+    end
+
+    def applied_count(messages, layer)
+      Array(messages).sum do |entry|
+        next 0 unless entry[:role].to_s == "tool_response"
+
+        LLMContextEdit.on(entry).values.count { |edit| edit.applied? && edit.kind == layer }
+      end
+    end
+  end
+end

data/lib/samagotchi/llm_context_override.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # A session's own llm_context values (Session#llm_context), which come
+  # before the model's, the host's and the global ones
+  # (LLMContextStrategy.resolve): the layers ([] is none, set on purpose),
+  # the apply rule and the budget in tokens (0 is off, set on purpose).
+  # nil in a field is unset: that value follows the model, the host, then
+  # llm_context.*, as with no override at all.
+  #
+  # Set by chi --llm-context, --llm-context-apply and --llm-context-budget
+  # at start (or --resume), /llm-context in the session and the web's info
+  # bar (which sends /llm-context). Saved in the session file, so a
+  # --resume and a respawned worker keep it; a plugin's fork copies it,
+  # a delegate child starts without one.
+  LLMContextOverride = Data.define(:strategy, :apply, :budget_tokens) do
+    def initialize(strategy: nil, apply: nil, budget_tokens: nil) = super
+
+    def empty? = strategy.nil? && apply.nil? && budget_tokens.nil?
+
+    # What the session file keeps: the set fields, nil when none is.
+    # @return [Hash, nil]
+    def to_file
+      return nil if empty?
+
+      { "strategy" => strategy&.map(&:to_s), "apply" => apply&.to_s, "budget_tokens" => budget_tokens }.compact
+    end
+
+    # LLMContextStrategy.resolve's session arguments.
+    def resolve_args = { session: strategy, session_apply: apply, session_budget: budget_tokens }
+
+    # How a field reads: "stale, forget", "none", "turn_end", "64000",
+    # "off"; nil when unset.
+    def self.word(field, value)
+      return nil if value.nil?
+
+      case field
+      when :strategy then value.empty? ? "none" : value.join(", ")
+      when :budget_tokens then value.positive? ? value.to_s : "off"
+      else value.to_s
+      end
+    end
+  end
+
+  class LLMContextOverride
+    FIELDS = %i[strategy apply budget_tokens].freeze
+    # A field's word for "unset: follow the model" (/llm-context strategy default).
+    DEFAULT_WORD = "default"
+    OFF_WORDS = %w[off 0].freeze
+    # The start flags (chi, chi send --new), by field.
+    FLAGS = { strategy: "--llm-context", apply: "--llm-context-apply", budget_tokens: "--llm-context-budget" }.freeze
+    # The session command, and its words by field.
+    COMMAND = "/llm-context"
+    COMMAND_WORDS = { strategy: "strategy", apply: "apply", budget_tokens: "budget" }.freeze
+
+    # The /llm-context line that sets +words+ (field => value as typed,
+    # checked by .update first): what a flag on an existing session runs.
+    # @return [String]
+    def self.command_line(words)
+      parts = words.map do |field, word|
+        word = word.to_s.strip
+        word = parse_strategy(word).then { |layers| layers.empty? ? "none" : layers.join(",") } if field == :strategy && !word.casecmp?(DEFAULT_WORD)
+        "#{COMMAND_WORDS.fetch(field)} #{word}"
+      end
+      [COMMAND, *parts].join(" ")
+    end
+
+    # A session file's "llm_context" (or an override already): nil when
+    # absent or empty. A field that doesn't read (an unknown layer, an
+    # out-of-range budget: a newer chi's, or a hand edit) is left unset,
+    # without a warning: that value follows the model (.unread keeps it).
+    # @return [LLMContextOverride, nil]
+    def self.from_file(data)
+      return data.empty? ? nil : data if data.is_a?(self)
+      return nil unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      override = new(strategy: file_value { file_strategy(data["strategy"]) },
+                     apply: file_value { parse_apply(data["apply"].to_s) unless data["apply"].nil? },
+                     budget_tokens: file_value { file_budget(data["budget_tokens"]) })
+      override.empty? ? nil : override
+    end
+
+    # The fields of a session file's "llm_context" that .from_file couldn't
+    # read, as written (String keys): saved back as they were.
+    # @return [Hash]
+    def self.unread(data)
+      return {} unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      read = from_file(data)
+      FIELDS.each_with_object({}) do |field, unread|
+        key = field.to_s
+        unread[key] = data[key] if !data[key].nil? && read&.public_send(field).nil?
+      end
+    end
+
+    def self.file_value
+      yield
+    rescue ArgumentError
+      nil
+    end
+
+    def self.file_strategy(raw)
+      return nil unless raw.is_a?(Array) || raw.is_a?(String)
+      return [] if raw == []
+
+      parse_strategy(Array(raw).join(","))
+    end
+
+    def self.file_budget(raw)
+      raw.is_a?(Integer) ? check_budget(raw) : nil
+    end
+
+    # +current+ with +words+ (field => what the user typed) applied: each
+    # word is a value, or "default" (unset). The flags and /llm-context
+    # both go through here.
+    # @param current [LLMContextOverride, nil]
+    # @param words [Hash{Symbol => String}]
+    # @return [LLMContextOverride]
+    # @raise [ArgumentError] a word that isn't a value, saying which
+    def self.update(current, words)
+      fields = words.to_h do |field, word|
+        raise ArgumentError, "unknown llm_context field #{field}" unless FIELDS.include?(field)
+
+        text = word.to_s.strip
+        [field, text.casecmp?(DEFAULT_WORD) ? nil : send(:"parse_#{field}", text)]
+      end
+      (current || new).with(**fields)
+    end
+
+    # "stale,forget", "stale forget", "stale|forget" or "none".
+    # @return [Array<Symbol>] [] for none
+    def self.parse_strategy(text)
+      names = text.downcase.split(/[\s,|]+/).reject(&:empty?)
+      raise ArgumentError, "a strategy is none or a list of #{LLMContextStrategy::LAYERS.join(", ")}" if names.empty?
+      return [] if names == [LLMContextStrategy::NONE.to_s]
+
+      unknown = names - LLMContextStrategy::LAYERS.map(&:to_s)
+      unless unknown.empty?
+        raise ArgumentError, "unknown llm_context strategy #{unknown.join(", ")} (none, or a list of " \
+                             "#{LLMContextStrategy::LAYERS.join(", ")})"
+      end
+      LLMContextStrategy::LAYERS.select { |layer| names.include?(layer.to_s) }
+    end
+
+    # payoff, next_request or turn_end.
+    # @return [Symbol]
+    def self.parse_apply(text)
+      rule = LLMContextStrategy::APPLIES.find { |name| name.to_s.casecmp?(text) }
+      rule || raise(ArgumentError, "unknown llm_context apply #{text} (#{LLMContextStrategy::APPLIES.join(", ")})")
+    end
+
+    # The smallest and largest budget a session may set.
+    MIN_BUDGET = 4_000
+    MAX_BUDGET = 10_000_000
+
+    # "64000", "64k" or "off" (0).
+    # @return [Integer] 0 for off
+    def self.parse_budget_tokens(text)
+      return 0 if OFF_WORDS.include?(text.downcase)
+
+      match = /\A(\d[\d_]*)(k)?\z/i.match(text)
+      raise ArgumentError, "a budget is a number of tokens (64000 or 64k) or off" unless match
+
+      check_budget(match[1].delete("_").to_i * (match[2] ? 1000 : 1))
+    end
+
+    # +tokens+, when 0 (off) or between MIN_BUDGET and MAX_BUDGET.
+    def self.check_budget(tokens)
+      return tokens if tokens.zero? || tokens.between?(MIN_BUDGET, MAX_BUDGET)
+
+      raise ArgumentError, "a budget of #{tokens} tokens is out of range: #{MIN_BUDGET} (4k) to #{MAX_BUDGET} (10000k), or off"
+    end
+
+    private_class_method :file_value, :file_strategy, :file_budget
+  end
+end

data/lib/samagotchi/llm_context_strategy.rb

@@ -7,8 +7,8 @@ module Samagotchi
   # llm_context_strategy (models.<key>, hosts.<name>), each a layer name,
   # "|"-separated names or a YAML list.
   #
-  # Resolution, first set wins: the session's own (a later per-session
-  # override; nothing sets it yet), models.<key> (by the model's lookup
+  # Resolution, first set wins: the session's own (Session#llm_context,
+  # set by chi --llm-context, /llm-context and the web), models.<key> (by the model's lookup
   # names, as window_tokens), hosts.<name>, then llm_context.strategy.
   # An unknown layer warns and is none (every layer is built: stale, and
   # forget, experimental, with its tool forget_outputs).
@@ -118,29 +118,71 @@ module Samagotchi
       nil
     end
 
+    # Where one value came from: :session, :model_setting, :host_setting
+    # or :config, and the place as a warning names it ("the session",
+    # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
+    Origin = Data.define(:source, :where)
+    SESSION_ORIGIN = Origin.new(source: :session, where: "the session")
+
+    # What a turn's strategy, apply rule and budget are, each with its
+    # Origin (/llm-context, /stats, the web's info bar).
+    Explained = Data.define(:resolved, :strategy, :apply, :budget_tokens) do
+      # The plain form /stats, the snapshot and the web read: each value
+      # with its source and place, and +own+, the session's own values
+      # (LLMContextOverride#to_file; nil without any).
+      # @return [Hash] symbol keys
+      def summary(own = nil)
+        layers = resolved.active_layers
+        { strategy: layers.empty? ? NONE.to_s : layers.join(","), strategy_source: strategy.source.to_s,
+          strategy_where: strategy.where, apply: resolved.apply.to_s, apply_source: apply.source.to_s,
+          apply_where: apply.where, budget_tokens: resolved.budget_tokens, budget_source: budget_tokens.source.to_s,
+          budget_where: budget_tokens.where, own: own&.to_file }
+      end
+    end
+
     # The strategy for +target+'s turn.
     # @param target [HostRegistry::ModelTarget, nil]
     # @param names [Array<String>] HostRegistry#lookup_names
     # @param models [Hash, nil] ConfigFile.model_settings (specs)
-    # @param session [Array<Symbol>, nil] the session's own layers (none yet)
-    # @param session_apply [Symbol, nil] the session's own apply rule (none yet)
-    # @param session_budget [Integer, nil] the session's own budget (none yet)
+    # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
+    # @param session_apply [Symbol, nil] the session's own apply rule
+    # @param session_budget [Integer, nil] the session's own budget (0: off)
     # @return [Resolved]
     def resolve(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
+      explain(target, names: names, models: models, session: session, session_apply: session_apply,
+                      session_budget: session_budget).resolved
+    end
+
+    # #resolve, with where each value came from.
+    # @return [Explained]
+    def explain(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
       models ||= ConfigFile.model_settings
       layers, source, where = layers_for(target, names, models, session)
-      resolved(layers, source, where).with(apply: apply_for(target, names, models, session_apply),
-                                           protect_steps: protect_steps, stale_edits: Config.get(STALE_EDITS_SETTING) == true,
-                                           budget_tokens: budget_for(target, names, models, session_budget))
+      apply, apply_origin = apply_for(target, names, models, session_apply)
+      budget, budget_origin = budget_for(target, names, models, session_budget)
+      resolved = resolved(layers, source, where).with(apply: apply, protect_steps: protect_steps,
+                                                      stale_edits: Config.get(STALE_EDITS_SETTING) == true,
+                                                      budget_tokens: budget)
+      Explained.new(resolved: resolved, strategy: Origin.new(source: source, where: where), apply: apply_origin,
+                    budget_tokens: budget_origin)
     end
 
+    # [the budget, its Origin]: the session's own first (0 there is off,
+    # whatever the model says).
     def budget_for(target, names, models, session_budget)
-      session_budget || ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)&.last ||
-        target&.entry&.llm_context_budget_tokens || parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING)
+      return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
+
+      key, budget = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)
+      return [budget, Origin.new(source: :model_setting, where: "models: #{key}")] if budget
+
+      budget = target&.entry&.llm_context_budget_tokens
+      return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
+
+      [parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING), Origin.new(source: :config, where: BUDGET_SETTING)]
     end
 
     def layers_for(target, names, models, session)
-      return [session, :session, "the session"] if session
+      return [session, :session, SESSION_ORIGIN.where] if session
 
       key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
       return [layers, :model_setting, "models: #{key}"] if layers
@@ -151,9 +193,17 @@ module Samagotchi
       [parse(Config.get(SETTING), SETTING) || [], :config, SETTING]
     end
 
+    # [the apply rule, its Origin].
     def apply_for(target, names, models, session_apply)
-      session_apply || ConfigFile.model_setting(names, :llm_context_apply, models: models)&.last ||
-        target&.entry&.llm_context_apply || parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY
+      return [session_apply, SESSION_ORIGIN] if session_apply
+
+      key, apply = ConfigFile.model_setting(names, :llm_context_apply, models: models)
+      return [apply, Origin.new(source: :model_setting, where: "models: #{key}")] if apply
+
+      apply = target&.entry&.llm_context_apply
+      return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply
+
+      [parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY, Origin.new(source: :config, where: APPLY_SETTING)]
     end
 
     # llm_context.protect_steps: 0 or more (a negative one is the default).

data/lib/samagotchi/memory_bundle/index_size.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../tools/memory"
+require_relative "../model_notes"
+
+module Samagotchi
+  module MemoryBundle
+    # The size of one scope's memory index as a prompt carries it: every
+    # session's system prompt holds both indexes in full, so their size is
+    # paid on every request. tokens is the estimate ContextStatus uses
+    # (characters / context.chars_per_token, rounded up), lines the
+    # non-blank lines, bytes the UTF-8 size.
+    #
+    # memory_write and write/edit on a memory compare the size before and
+    # after a write against memory.index_warn_tokens (#crossing_note);
+    # chi self shows it (#summary), and a session's figure comes from the
+    # index text its prompt holds (SystemPrompt).
+    IndexSize = Data.define(:scope, :bytes, :lines, :tokens) do
+      # @param text [String, nil] the index text
+      # @param chars_per_token [Float]
+      # @return [IndexSize]
+      def self.of_text(scope, text, chars_per_token: self.chars_per_token)
+        text = text.to_s
+        new(scope: scope.to_s, bytes: text.bytesize, lines: text.each_line.count { |line| !line.strip.empty? },
+            tokens: (text.length / chars_per_token).ceil)
+      end
+
+      # +scope+'s index as the prompt carries it before a session's own
+      # filters (mutes): index.md, or the file listing without one, minus
+      # the model notes' lines (ModelNotes.filter_index).
+      # @param env [Hash] the XDG env the memories dir resolves from
+      # @return [IndexSize]
+      def self.of_scope(scope, chars_per_token: self.chars_per_token, env: ENV)
+        text = Tools::MemoryRead.scoped_index(scope, env: env)
+        of_text(scope, ModelNotes.filter_index(text, scope, env: env), chars_per_token: chars_per_token)
+      end
+
+      # of_scope, or nil when the index can't be read (a write's measure
+      # must never fail the write).
+      def self.measure(scope)
+        of_scope(scope)
+      rescue StandardError
+        nil
+      end
+
+      # context.chars_per_token, 4.0 when it isn't positive.
+      def self.chars_per_token
+        value = Config.get("context.chars_per_token").to_f
+        value.positive? ? value : 4.0
+      rescue StandardError
+        4.0
+      end
+
+      # memory.index_warn_tokens: the tokens one scope's index may hold
+      # before a write that crosses it gets a note; 0 turns the note off.
+      def self.warn_limit
+        Config.get("memory.index_warn_tokens").to_i
+      rescue StandardError
+        0
+      end
+
+      # The note a write gets when it took the index from at or under
+      # +limit+ to over it, nil otherwise: once per crossing, so a write
+      # while the index is already over gets none and the note doesn't
+      # start a loop of small tightenings. Sessions sharing the dir measure
+      # on their own (before and after aren't one locked step), so writes
+      # in parallel sessions racing over the limit may each get it.
+      # @param before [IndexSize, nil]
+      # @param after [IndexSize, nil]
+      # @return [String, nil]
+      def self.crossing_note(before, after, limit = warn_limit)
+        return nil unless before && after && after.over?(limit) && !before.over?(limit)
+
+        "Note: the #{after.scope} memory index is now ~#{after.tokens} tokens (over memory.index_warn_tokens " \
+          "#{limit}) and is sent with every prompt. When you next have a moment, tighten long index " \
+          "descriptions (memory_write with name, scope and description only). Don't remove or merge memories " \
+          "unless the user asks."
+      end
+
+      # "450", "2.0k": a token count as the size readouts show it (the
+      # web's ctx.js memoryIndexText too; spec/shared/labels_matrix.json).
+      def self.count_text(tokens)
+        value = tokens.to_i
+        value >= 1000 ? "#{format("%.1f", (value / 100.0).round / 10.0)}k" : value.to_s
+      end
+
+      # Whether the index holds more than +limit+ tokens; a limit that
+      # isn't positive is off.
+      def over?(limit) = limit.to_i.positive? && tokens > limit.to_i
+
+      # "system ~2.0k tokens (54 lines)", with ", over 2500" in the
+      # parentheses when over +limit+: chi self's row.
+      def summary(limit = 0)
+        over = over?(limit) ? ", over #{limit}" : ""
+        "#{scope} ~#{self.class.count_text(tokens)} tokens (#{lines} #{lines == 1 ? "line" : "lines"}#{over})"
+      end
+
+      # { tokens:, lines: }: the session's block (SessionMetrics).
+      def figures = { tokens: tokens, lines: lines }
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/index_sync.rb

@@ -38,7 +38,7 @@ module Samagotchi
       end
 
       # "project" or "system" when +path+ is a memory's file (or an
-      # overlay's): a *.md right in that scope's memories dir, not index.md,
+      # overlay's): a *.md right in that scope's memories dir, not index.md (in any case),
       # not hidden, not a symlink. nil otherwise. The guardrails' outside_repo
       # uses it too: write/edit there is what memory_write does. A symlink
       # isn't: write/edit follow it to wherever it points, memory_write
@@ -47,7 +47,8 @@ module Samagotchi
         path = File.expand_path(path.to_s)
         name = File.basename(path, ".md")
         return nil unless File.extname(path) == ".md"
-        return nil if name == IndexUpdater::MEMORY_INDEX || name.start_with?(".") || File.symlink?(path)
+        # Any case: on a case-insensitive disk INDEX.md is the index itself.
+        return nil if name.casecmp?(IndexUpdater::MEMORY_INDEX) || name.start_with?(".") || File.symlink?(path)
 
         dir = real(File.dirname(path))
         SCOPES.find { |s| real(Tools::MemoryRead.memories_dir(s)) == dir }

data/lib/samagotchi/model_match.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Which models a `models:` list is for, in one grammar shared by the
+  # guardrails rules' `models:`, `guardrails.small_models` and the model
+  # notes' first line: entries `|`-separated (or a list), each `small` (the
+  # caller says whether the model is a small one) or an fnmatch glob
+  # (case-insensitive, extglob) on the bare model name or the model key
+  # (ModelOverlay.key_for). Any entry matching wins; no model matches
+  # nothing.
+  module ModelMatch
+    GLOB_FLAGS = File::FNM_CASEFOLD | File::FNM_EXTGLOB
+    SMALL = "small"
+    # A model note's first line (ModelNotes): `models: …`, any case, after
+    # an optional UTF-8 BOM.
+    MODELS_LINE = /\A\uFEFF?\s*models:(.*)\z/i
+
+    module_function
+
+    # The entries of a `models:` value: a string, or a list of them, each
+    # split on `|`, stripped, blanks dropped.
+    # @param value [String, Array<String>, nil]
+    # @return [Array<String>]
+    def parse(value)
+      Array(value).flat_map { |entry| entry.to_s.split("|") }.map(&:strip).reject(&:empty?)
+    end
+
+    # The entries of +text+'s first line when it is a `models:` line with
+    # at least one; nil otherwise.
+    # @return [Array<String>, nil]
+    def models_line(text)
+      first = text.to_s.each_line.first.to_s.chomp
+      match = first.match(MODELS_LINE)
+      entries = match && parse(match[1])
+      entries unless entries.nil? || entries.empty?
+    end
+
+    # @param entries [Array<String>] parsed entries (#parse)
+    # @param name [String, nil] the bare model name
+    # @param key [String, nil] its model key
+    # @param small [#call] → whether the model is a small one; called only
+    #   for a `small` entry
+    def match?(entries, name:, key:, small:)
+      return false if name.nil? || name.to_s.empty?
+
+      entries.any? { |entry| entry == SMALL ? small.call : glob?(entry, name: name, key: key) }
+    end
+
+    # Whether the glob +entry+ matches the name or the key.
+    def glob?(entry, name:, key:)
+      [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate.to_s, GLOB_FLAGS) }
+    end
+  end
+end