samagotchi 0.40.0 → 0.42.0

data/lib/samagotchi/system_prompt.rb

@@ -7,14 +7,16 @@ require_relative "memory_paths"
 require_relative "tool_declarations"
 require_relative "tools/memory"
 require_relative "muted_memories"
+require_relative "model_notes"
 require_relative "bundle_needs"
+require_relative "memory_bundle/index_size"
 require_relative "thinking"
 
 module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
   # declarations and call syntax for the raw-prompt loop, none for the chat
   # loop, the shared guidance) and around it the thinking token, rg
-  # guidance, the identity memory, the preloaded memories, AGENT.md, the
+  # guidance, the identity memory, the model notes, the preloaded memories, AGENT.md, the
   # memory indexes and, last, the model, where the session runs and the
   # session (#system_prompt_with_index has the order and why).
   #
@@ -45,11 +47,15 @@ module Samagotchi
     # @param session  [#call] → Session, nil
     # @param thinking [#call] → Symbol, the effective model's level (Thinking)
     # @param model    [#call] → ModelIdentity, nil (the section is left out)
+    # @param model_notes [#call] → Array<ModelNotes::Note>, the effective
+    #   model's (none: the section is left out)
     # @param memories [Array<String>] the --memory list
     # @param muted_memory_names [Array<String>] normalized (MutedMemories)
-    def initialize(profile:, tools:, session:, thinking:, model: -> {}, memories: [], muted_memory_names: [])
+    def initialize(profile:, tools:, session:, thinking:, model: -> {}, model_notes: -> { [] }, memories: [],
+                   muted_memory_names: [])
       @profile_lookup = profile
       @model_lookup = model
+      @model_notes_lookup = model_notes
       @tools_lookup = tools
       @session_lookup = session
       @thinking_lookup = thinking
@@ -71,16 +77,44 @@ module Samagotchi
     # @param layers [Array<Symbol>] the turn's LLM context layers: the
     #   native prompt declares the tools they add (Tools::Registry#entries)
     def build(chat: false, thinking: nil, layers: [])
+      key = [chat, thinking, layers]
       @built ||= {}
-      @built[[chat, thinking, layers]] ||= system_prompt_with_index(
-        assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat, thinking: thinking, layers: layers
-      )
+      @index_sizes ||= {}
+      @notes_loaded ||= {}
+      unless @built.key?(key)
+        @section_notes = nil
+        @built[key] = system_prompt_with_index(
+          assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat, thinking: thinking, layers: layers
+        )
+        @index_sizes[key] = @measured_index
+        @notes_loaded[key] = @section_notes || []
+      end
+      @memory_index = @index_sizes[key]
+      @prompt_notes = @notes_loaded[key]
+      @built[key]
     end
 
+    # The memory indexes the prompt #build returned last holds, per scope
+    # ({ system: { tokens:, lines: }, project: { … } }; MemoryBundle::IndexSize
+    # of the text after the session's mutes and the model notes' lines), nil
+    # before a build. Measured when the prompt is built: a memory write
+    # during the session changes neither the prompt nor this.
+    # @return [Hash, nil]
+    attr_reader :memory_index
+
+    # The model notes the prompt #build returned last carries
+    # (Array<ModelNotes::Note>, [] with none), nil before a build and after
+    # #reset!. Read when the prompt is built, as the section is.
+    # @return [Array<ModelNotes::Note>, nil]
+    attr_reader :prompt_notes
+
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
       @built = nil
+      @index_sizes = nil
+      @notes_loaded = nil
+      @prompt_notes = nil
       @stable_lengths = nil
     end
 
@@ -254,11 +288,13 @@ module Samagotchi
     # still follow them).
     def system_prompt_with_index(base, chat: false, thinking: nil, layers: [])
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
+      indexes = { project: read_memory_index("project"), system: read_memory_index("system") }
+      @measured_index = measure_indexes(indexes)
       memory_sections = [
-        "Project memories:\n#{read_memory_index("project")}",
-        "System memories:\n#{read_memory_index("system")}"
+        "Project memories:\n#{indexes[:project]}",
+        "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
-      stable = [thinking_token + base, rg_guidance, system_identity_section, explicit_memory_section,
+      stable = [thinking_token + base, rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
                 project_specific_description, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [current_model, project_location, current_session].compact
@@ -295,6 +331,23 @@ module Samagotchi
       nil
     end
 
+    # The model notes for the session's model (ModelNotes), right after
+    # identity: a heading per scope, each note under its name, the models:
+    # line left out. nil without any, so the prompt stays as it was.
+    def model_notes_section
+      @section_notes = []
+      notes = Array(@model_notes_lookup.call)
+      return nil if notes.empty?
+
+      ref = @model_lookup.call&.ref
+      notes.group_by(&:scope).map do |scope, list|
+        heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
+        [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
+      end.join("\n\n").tap { @section_notes = notes }
+    rescue StandardError
+      nil
+    end
+
     # ── Memory helpers ─────────────────────────────────────────────────────────
 
     # The session model's overlay keys, so the prompt's own memory bodies
@@ -308,9 +361,23 @@ module Samagotchi
       {}
     end
 
-    # The scope's index text without the muted memories' lines.
+    # { system: { tokens:, lines: }, project: { … } } of the index texts
+    # the prompt holds; nil when they can't be measured.
+    def measure_indexes(indexes)
+      chars_per_token = MemoryBundle::IndexSize.chars_per_token
+      %i[system project].to_h do |scope|
+        [scope, MemoryBundle::IndexSize.of_text(scope, indexes[scope], chars_per_token: chars_per_token).figures]
+      end
+    rescue StandardError
+      nil
+    end
+
+    # The scope's index text without the muted memories' lines, nor the
+    # model notes' (their bodies are in their own section, or not for this
+    # model).
     def read_memory_index(scope)
-      BundleNeeds.annotate_index(MutedMemories.filter_index(Tools::MemoryRead.call("", scope: scope), @muted_memory_names), scope)
+      index = MutedMemories.filter_index(Tools::MemoryRead.call("", scope: scope), @muted_memory_names)
+      BundleNeeds.annotate_index(ModelNotes.filter_index(index, scope), scope)
     end
 
     # Merge the config.yml `memories:` baseline with the explicit `--memory`
@@ -473,7 +540,8 @@ module Samagotchi
       "Model: this session runs on #{model.ref}#{where}.\n" \
         "Asked which model you are, answer with this line, not from training: a fine-tuned model often knows only " \
         "its base model's name, but this session runs what is named here; it changes only with /model. " \
-        "Guidance for this model only goes in memory overlays: memory_write current_model_only: true."
+        "Guidance for this model only goes in a model note: a memory named model_notes_<name> whose first line is " \
+        "`models: <glob on this model's id or key>`."
     rescue StandardError
       nil
     end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -36,14 +36,21 @@ module Samagotchi
       # @param memories [Array<String>] --memory: a new session's worker
       #   preloads them (an existing session keeps its own list)
       # @param muted_memories [Array<String>] --mute: hidden from a new session
+      # @param llm_context [Hash{Symbol => String}] --llm-context* as typed
+      #   (LLMContextOverride.update): a new session starts with them; a
+      #   resumed or attached one's worker gets a /llm-context, after the
+      #   /model
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [])
+              memories: [], muted_memories: [], llm_context: {})
         client = connect(attach: attach, shared: shared, resume: resume, model: model,
-                         memories: memories, muted_memories: muted_memories)
-        first_command = model && (attach || resume) ? "/model #{model}" : nil
+                         memories: memories, muted_memories: muted_memories, llm_context: llm_context)
+        commands = []
+        commands << "/model #{model}" if model && (attach || resume)
+        commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
+        first_command = commands.size > 1 ? commands : commands.first
         surface = open_surface
         attached = AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
                                     first_command: first_command, no_interrupt: no_interrupt,
@@ -104,7 +111,7 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, err: $stderr)
         sd = state_dir || Session.default_state_dir
         warn_memory_flags_ignored(attach || resume, memories, muted_memories, err) if attach || resume
         if attach
@@ -119,7 +126,8 @@ module Samagotchi
                     SessionManager.resume_session(resume, state_dir: sd)
                   else
                     SessionManager.spawn_session(prompt: nil, model_name: model && model_ref(model), state_dir: sd,
-                                                 memories: memories, muted_memories: muted_memories)
+                                                 memories: memories, muted_memories: muted_memories,
+                                                 llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -82,8 +82,9 @@ module Samagotchi
       #   PlainSurface when the terminal can't show a live region)
       # @param client_id [String] this UI's id in the events ("tui:<pid>")
       # @param first_prompt [String, nil] sent once joined (`chi -p`)
-      # @param first_command [String, nil] run before the first prompt
-      #   (`--model` on a resumed session: "/model X"); if it doesn't go
+      # @param first_command [String, Array<String>, nil] run before the
+      #   first prompt, in order (`--model` on a resumed session: "/model X";
+      #   --llm-context: "/llm-context strategy …"); if one doesn't go
       #   through, the launch stops
       # @param no_interrupt [Boolean] post every turn with no_interrupt
       # @param default_input [Boolean] type SAMAGOTCHI_DEFAULT_INPUT into
@@ -127,7 +128,7 @@ module Samagotchi
         @answered_ids = Set.new
         @reader = nil
         @first_prompt = first_prompt
-        @first_command = first_command
+        @first_commands = Array(first_command)
         @first_command_id = nil
         @no_interrupt = no_interrupt
         @no_default_input = !default_input
@@ -521,6 +522,9 @@ module Samagotchi
           return
         end
         return @screen.commit(stale_worker("run commands")) if reply.status == 404
+
+        name = older_worker_command(reply, line)
+        return @screen.commit(stale_worker("run #{name}")) if name
         return @screen.commit("could not run the command (#{LATE})") if too_late?(reply)
 
         detail = reply.json&.fetch("detail", nil) || reply.json&.fetch("error", nil)
@@ -827,6 +831,14 @@ module Samagotchi
       # so it shows above what it got.
       def echo_answer(text) = @screen.commit("#{paint(QUESTION_PROMPT, 33)}#{text}")
 
+      # The name of this chi's own command +line+ when the worker answered it
+      # unknown_command (it runs an older chi without it), else nil.
+      def older_worker_command(reply, line)
+        return nil unless reply.status == 400 && reply.json&.fetch("error", nil) == "unknown_command"
+
+        SessionCommands.builtin_name(line)
+      end
+
       def stale_worker(cant)
         BridgeClient.stale_worker_message(@client.session_id, cant: cant)
       end
@@ -980,18 +992,19 @@ module Samagotchi
           @shown_enqueued << entry[:enqueued_id]
           @screen.commit("queued #{prompt_line(entry[:client_id], entry[:prompt])}")
         end
-        return send_first_command if @first_command
+        return send_first_command unless @first_commands.empty?
 
         send_first_prompt
         nil
       end
 
-      # --model on a resumed session: switch its worker before the first
-      # prompt goes; its :command_ran decides (#first_command_ran).
+      # --model (or --llm-context) on a resumed session: run it in its
+      # worker before the first prompt goes; its :command_ran decides
+      # (#first_command_ran), and sends the next one.
       # @return [Symbol, nil] :failed when the worker didn't take it
       def send_first_command
-        line = @first_command
-        @first_command = nil
+        line = @first_commands.shift
+        @first_command_line = line
         reply = @client.post_command(line: line, client_id: @client_id)
         if reply.status == 202
           @first_command_id = reply.json&.fetch("command_id", nil)
@@ -1000,28 +1013,35 @@ module Samagotchi
 
         why =
           if reply.status == 404 then stale_worker("run commands")
+          elsif (name = older_worker_command(reply, line)) then stale_worker("run #{name}")
           elsif too_late?(reply) then LATE
           else "the worker answered #{reply.status}"
           end
-        @screen.commit("could not switch to the --model: #{why}")
+        @screen.commit("#{first_command_failed}: #{why}")
         :failed
       rescue SystemCallError, IOError => e
-        @screen.commit("could not switch to the --model: #{worker_down(e)}")
+        @screen.commit("#{first_command_failed}: #{worker_down(e)}")
         :failed
       end
 
-      # @return [Symbol, nil] :failed unless the switch went through
+      # @return [Symbol, nil] :failed unless the command went through
       def first_command_ran(event)
         @first_command_id = nil
         if event[:status] == "ok"
+          return send_first_command unless @first_commands.empty?
+
           send_first_prompt
           return nil
         end
 
-        @screen.commit("could not switch to the --model: #{event[:output]}")
+        @screen.commit("#{first_command_failed}: #{event[:output]}")
         :failed
       end
 
+      def first_command_failed
+        @first_command_line.to_s.start_with?("/model") ? "could not switch to the --model" : "could not set the --llm-context"
+      end
+
       # After the join, so it lands below what the session already had. Our
       # own prompts are never echoed from events (a typed one stays on screen),
       # so it is shown here as if typed.

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -94,6 +94,8 @@ module Samagotchi
           # that couldn't be used).
           @view.finish_thinking_spinner
           @view.print_line(@view.turn_failed_line(event[:summary] || event[:message], event[:duration_ms]))
+          # Its work so far stayed (the Engine's kept_steps), as after a cancel.
+          @view.print_line(@view.turn_end_hint(Formatting::ROLLBACK_HINT)) if event[:kept_steps] && !@turn_continues
         when :guardrail_warning
           @view.print_line(self.class.load_warning_line(event))
         when :hook_notice

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -5,6 +5,8 @@ require_relative "../served_model"
 require_relative "../image_store"
 require_relative "../turn_note"
 require_relative "../steer"
+require_relative "../memory_bundle/index_size"
+require_relative "../prompt_note"
 
 module Samagotchi
   class TerminalUI
@@ -314,6 +316,25 @@ module Samagotchi
         "#{"~" if source.to_s == "estimate"}#{number} tok/s"
       end
 
+      # "~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)":
+      # the memory indexes the session's prompt holds (the snapshot's
+      # memory_index, symbol or string keys); "" without one. As ctx.js
+      # memoryIndexText (spec/shared/labels_matrix.json).
+      def memory_index_text(block)
+        return "" unless block.is_a?(Hash)
+
+        scopes = %w[system project].filter_map do |scope|
+          figures = block[scope] || block[scope.to_sym]
+          tokens = figures.is_a?(Hash) ? (figures["tokens"] || figures[:tokens]) : nil
+          [scope, tokens.to_i] if tokens.is_a?(Numeric)
+        end
+        return "" if scopes.empty?
+
+        count = ->(tokens) { MemoryBundle::IndexSize.count_text(tokens) }
+        "~#{count.call(scopes.sum(&:last))} tokens in this session's prompt " \
+          "(#{scopes.map { |scope, tokens| "#{scope} #{count.call(tokens)}" }.join(", ")})"
+      end
+
       # "$0.42"; a cost under a cent keeps four decimals ("$0.0012"); "" for
       # none. As ctx.js costText.
       def cost_text(cost)
@@ -463,6 +484,13 @@ module Samagotchi
         end
         lines << "context window:   #{context[:window_tokens]} tokens (#{context[:window_source]})" if context[:window_tokens]
         lines << "prompt profile:   #{snapshot[:profile]} (#{snapshot[:profile_source]})" if snapshot[:profile]
+        memory_index = memory_index_text(snapshot[:memory_index])
+        lines << "memory index:     #{memory_index}" unless memory_index.empty?
+        # The model notes the session's prompt carried (Engine#prompt_notes).
+        notes = PromptNote.text(snapshot[:prompt_notes])
+        lines << "model notes:      #{notes}" unless notes.empty?
+        llm_context = llm_context_stats_text(snapshot[:llm_context])
+        lines << "llm context:      #{llm_context}" if llm_context
         if snapshot[:served_model]
           asked = snapshot[:served_model_for]
           note = ServedModel.differs?(asked, snapshot[:served_model]) ? " (asked for #{asked})" : ""
@@ -471,6 +499,18 @@ module Samagotchi
         lines.join("\n")
       end
 
+      # "stale,forget (the session); apply turn_end (models: x); budget
+      # 64000 (the session)" for /stats (Explained#summary; symbol or
+      # string keys, the attached TUI's come as JSON); nil without one.
+      def llm_context_stats_text(summary)
+        return nil unless summary.is_a?(Hash)
+
+        get = ->(key) { summary[key] || summary[key.to_s] }
+        budget = get.call(:budget_tokens) ? "#{get.call(:budget_tokens)} tokens" : "off"
+        "#{get.call(:strategy)} (#{get.call(:strategy_where)}); apply #{get.call(:apply)} (#{get.call(:apply_where)}); " \
+          "budget #{budget} (#{get.call(:budget_where)})"
+      end
+
       # ", cached 4864 (93%), cache writes 312, re-prefilled 2100, reasoning
       # 212" for the tokens line; the counts a server didn't report are left
       # out (re-prefilled: SessionMetrics' reprefill_sum).

data/lib/samagotchi/terminal_ui.rb

@@ -85,10 +85,13 @@ module Samagotchi
 
     # @param scratch [Boolean] `chi scratch`: a new session that is deleted
     #   however the REPL ends, saves no memories and writes no recap
+    # @param llm_context [Hash{Symbol => String}] --llm-context* as typed
+    #   (LLMContextOverride.update): set on the new or resumed session
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
-                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false)
+                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {})
       @scratch        = scratch
       @prompt         = prompt
+      @llm_context_words = llm_context
       @default_model_name = ModelProfile.required_model_name(nil)
       # As typed: the Engine applies an alias where it resolves the model.
       flag_model_name = model_name.to_s.strip.empty? ? nil : ModelProfile.required_model_name(model_name)
@@ -238,6 +241,12 @@ module Samagotchi
         muted_memory_names: @muted_memory_names,
         scratch: @scratch
       ))
+      # --llm-context*: the session's own values, over a resumed one's.
+      # Saved at once on a resumed one: leaving before a turn keeps them.
+      unless @llm_context_words.empty?
+        session.llm_context = LLMContextOverride.update(session.llm_context, @llm_context_words)
+        session.save if @resume_session
+      end
       claim_session!(session.id) unless @owner_lock
       keep_cards(session)
       # Saved at once, so a process killed before its first turn leaves a
@@ -759,20 +768,21 @@ module Samagotchi
       rescue LLM::ProviderError, ImageStore::Error => e
         # Engine closed the turn (:turn_failed), which the renderer showed.
         # An @path image that can't be used fails the turn the same way.
-        summary = e.respond_to?(:summary) ? e.summary : e.message
         # The model reads why on its next turn. An image that couldn't be
         # used, or that the host refused, never reached it: no note for that
         # (a first turn refused that way leaves the session empty, as before).
-        note = TurnNote.failed(summary, restored: true) if e.is_a?(LLM::ProviderError) && !e.is_a?(LLM::VisionUnsupported)
-        @turn_flow.prompt_turn_failed(note: note)
+        note = e.is_a?(LLM::ProviderError) && !e.is_a?(LLM::VisionUnsupported)
+        # A turn that got somewhere stays (the renderer said so, and that
+        # !rollback erases it), as the Engine saved it: no prompt goes back.
+        kept = @turn_flow.prompt_turn_failed(error: e, note: note) == :kept
         # The Engine saved the failed turn; the file follows the rollback.
-        save_session(session) if note
+        save_session(session) if note || kept
         if piped_input?
           # Nobody can edit a restored prompt, and Reline would hand it back
           # as the next line: the turn would run again and again. It failed;
           # the exit status says so.
           @piped_turn_failed = true
-        else
+        elsif !kept
           @surface.commit(turn_end_hint(restore_prompt_for_retry(input)))
         end
         return

data/lib/samagotchi/tool_runner.rb

@@ -8,6 +8,7 @@ require_relative "log"
 require_relative "edit_preview"
 require_relative "tools/tool_path"
 require_relative "memory_bundle/index_sync"
+require_relative "memory_bundle/index_size"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -71,9 +72,12 @@ module Samagotchi
         waited_ms = ((@clock.call - asked_at) * 1000).round
       end
       before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
+      index_before = before.equal?(NOT_AN_EDIT) ? nil : memory_index_size(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
       diff = file_change(call, before)
-      refresh_memory_index(call) if diff
+      if diff && refresh_memory_index(call)
+        result = with_index_note(result, index_before, call)
+      end
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -154,6 +158,27 @@ module Samagotchi
       MemoryBundle::IndexSync.refresh(Tools::ToolPath.normalize(call[:path]))
     end
 
+    # The index size of the memory scope an edit/write's path is in
+    # (MemoryBundle::IndexSize), nil for any other path, or when
+    # memory.index_warn_tokens is off: other writes cost nothing.
+    def memory_index_size(call)
+      scope = MemoryBundle::IndexSync.memory_scope(Tools::ToolPath.normalize(call[:path]))
+      return nil unless scope && MemoryBundle::IndexSize.warn_limit.positive?
+
+      MemoryBundle::IndexSize.measure(scope)
+    rescue StandardError
+      nil
+    end
+
+    # +result+ with the note memory_write gives when the refreshed index
+    # line took the scope's index over memory.index_warn_tokens.
+    def with_index_note(result, before, call)
+      return result unless before
+
+      note = MemoryBundle::IndexSize.crossing_note(before, memory_index_size(call))
+      note ? result.merge(output: "#{result[:output]}\n\n#{note}") : result
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/memory.rb

@@ -5,11 +5,14 @@ require "digest"
 require "date"
 require_relative "../atomic_file"
 require_relative "../memory_paths"
+require_relative "../model_match"
 
 module Samagotchi
   module Tools
     MEMORY_INDEX = "index"
     VALID_SCOPES = %w[project system].freeze
+    # Model notes (ModelNotes): `model_notes_<name>`, no dot in the name.
+    MODEL_NOTES_PREFIX = "model_notes_"
 
     # Reads a memory entry from scoped memory directories.
     # When scope is omitted, reads from project first and falls back to system.
@@ -111,8 +114,11 @@ module Samagotchi
         raise ArgumentError, "invalid scope '#{scope}', expected one of: #{VALID_SCOPES.join(", ")}"
       end
 
-      def self.scoped_index(scope)
-        dir = memories_dir(scope)
+      # +scope+'s index.md, or a listing of its files when it has none: what
+      # a session's prompt carries for the scope (before its filters).
+      # @param env [Hash] the XDG env the memories dir resolves from
+      def self.scoped_index(scope, env: ENV)
+        dir = memories_dir(scope, env: env)
         index_path = File.join(dir, "#{MEMORY_INDEX}.md")
         return File.read(index_path, encoding: "UTF-8") if File.exist?(index_path)
 
@@ -170,6 +176,14 @@ module Samagotchi
 
           return remove(entry_name, scope)
         end
+        if entry_name.include?(",")
+          return "Error: invalid memory name '#{entry_name}': no commas (memory_read reads a comma list of names); " \
+                 "use '#{entry_name.tr(",", "_")}'"
+        end
+        return dotted_model_note_error(entry_name) if dotted_model_note?(entry_name)
+        if (error = model_note_body_error(entry_name, body, current_model_only))
+          return error
+        end
 
         description = normalize_description(description)
         if description && description.length > DESCRIPTION_LIMIT
@@ -210,6 +224,9 @@ module Samagotchi
         end
 
         file_path = File.join(dir, "#{entry_name}.md")
+        # The index's size before the write, for the note on crossing
+        # memory.index_warn_tokens (not for the verbatim index write).
+        before = index_size(resolved_scope) unless entry_name == MEMORY_INDEX
         if entry_name == MEMORY_INDEX
           Samagotchi::MemoryBundle::IndexUpdater.locked_write(dir) { body }
         else
@@ -222,6 +239,7 @@ module Samagotchi
         # trigger upsert logic.
         if !(entry_name == MEMORY_INDEX) && manage_index(resolved_scope, entry_name, bytes, description)
           message += " Index line refreshed automatically."
+          message += index_crossing_note(before, resolved_scope)
         end
 
         message
@@ -229,6 +247,34 @@ module Samagotchi
         "Error: #{e.message}"
       end
 
+      # A model note's name with a dot would read as a model overlay
+      # (`<name>.<key>.md`) next to a note of the stem's name.
+      def self.dotted_model_note?(name) = name.start_with?(MODEL_NOTES_PREFIX) && name.include?(".")
+
+      def self.dotted_model_note_error(name)
+        "Error: invalid model note name '#{name}': no dot after #{MODEL_NOTES_PREFIX} (a dotted name reads as a " \
+          "model overlay); use '#{undotted(name)}'"
+      end
+
+      # +name+ with its dots made dashes, a trailing ".md" dropped first
+      # (`model_notes_x.md` → `model_notes_x`).
+      def self.undotted(name) = name.delete_suffix(".md").tr(".", "-")
+
+      # A model note's content must start with its models: line, or the note
+      # would never load (and its index line would hide it from no one). Its
+      # model overlay (current_model_only) has none.
+      def self.model_note_body_error(name, body, current_model_only)
+        return nil unless name.start_with?(MODEL_NOTES_PREFIX) && !body.empty? && !current_model_only
+        return nil if ModelMatch.models_line(body)
+
+        first = body.each_line.first.to_s.strip
+        first = "#{first[0, 60]}…" if first.length > 60
+        "Error: model note '#{name}' needs a first line saying which models it is for, `models: <glob>|small|…` " \
+          "(e.g. `models: deepseek-*|small`: globs on the model id or key, small per guardrails.small_models), " \
+          "then the note; the first line is #{first.empty? ? "empty" : "`#{first}`"}. A memory that isn't a model " \
+          "note needs a name without the #{MODEL_NOTES_PREFIX} prefix."
+      end
+
       # A description as the index line takes it: whitespace (newlines too)
       # collapsed to single spaces; nil when blank, which keeps the stored one.
       def self.normalize_description(description)
@@ -251,8 +297,29 @@ module Samagotchi
         file_path = File.join(MemoryRead.memories_dir(resolved_scope), "#{entry_name}.md")
         return "Error: no memory '#{entry_name}' in #{resolved_scope} scope; pass content to create it" unless File.file?(file_path)
 
+        # Measured around the call, whatever manage_index returns.
+        before = index_size(resolved_scope)
         manage_index(resolved_scope, entry_name, File.size(file_path), description)
-        "Memory '#{entry_name}' description updated in #{resolved_scope} scope (file unchanged)."
+        "Memory '#{entry_name}' description updated in #{resolved_scope} scope (file unchanged)." \
+          "#{index_crossing_note(before, resolved_scope)}"
+      end
+
+      # +scope+'s index size (MemoryBundle::IndexSize), or nil when
+      # memory.index_warn_tokens is off or the index can't be read.
+      def self.index_size(scope)
+        require_relative "../memory_bundle/index_size"
+        size = Samagotchi::MemoryBundle::IndexSize
+        size.measure(scope) if size.warn_limit.positive?
+      end
+
+      # "\n\nNote: the <scope> memory index is now ~N tokens …" when the
+      # write took +scope+'s index from at or under memory.index_warn_tokens
+      # to over it (+before+: its size before the write), else "".
+      def self.index_crossing_note(before, scope)
+        return "" unless before
+
+        note = Samagotchi::MemoryBundle::IndexSize.crossing_note(before, index_size(scope))
+        note ? "\n\n#{note}" : ""
       end
 
       # remove: true. Moves <name>.md and its model overlays into one