samagotchi 0.40.0 → 0.41.0

data/lib/samagotchi/model_notes.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "log"
+require_relative "model_match"
+require_relative "model_overlay"
+require_relative "memory_paths"
+require_relative "muted_memories"
+require_relative "tools/memory"
+require_relative "guardrails/model_size"
+
+module Samagotchi
+  # Model notes: memories named `model_notes_<name>` whose first line says
+  # which models they are for, in ModelMatch's grammar:
+  #
+  #   models: deepseek-*|*deepseek-v4*
+  #   Working habits for this model: ...
+  #
+  # Every note matching the session's model is loaded into the system
+  # prompt (SystemPrompt#model_notes_section, after identity), stacked: the
+  # system scope's, then the project's, by name within a scope. Notes add
+  # habits; none overrides another. The body is read through memory_read,
+  # so a note's own model overlays are appended as for any memory; the
+  # models: line is left out. Their index lines are left out of the
+  # prompt's indexes (#filter_index): the body is already there.
+  module ModelNotes
+    PREFIX = Tools::MODEL_NOTES_PREFIX
+    SCOPES = %w[system project].freeze
+    # A note over this, or all of them over TOTAL_LIMIT, still loads but
+    # warns once: they cost every request.
+    NOTE_LIMIT = 1_500
+    TOTAL_LIMIT = 3_000
+
+    # name: the memory name; scope: "system" or "project"; body: what the
+    # prompt carries (overlays appended, the models: line dropped); chars:
+    # its length; digest: a short SHA-256 of it.
+    Note = Data.define(:name, :scope, :body, :chars, :digest)
+
+    @warned = Set.new
+    @warn_mutex = Mutex.new
+
+    module_function
+
+    # The notes for a model.
+    # @param name [String, nil] the bare model id (no host prefix)
+    # @param key [String, nil] its model key (ModelOverlay.key_for)
+    # @param fallback_key [String, nil] the overlay key read when +key+ has
+    #   none (SystemPrompt::ModelIdentity#fallback_key)
+    # @param muted [Array<String>] the session's muted names (MutedMemories)
+    # @param small [#call, nil] → whether the model is a small one; nil:
+    #   guardrails.small_models (Guardrails::ModelSize)
+    # @return [Array<Note>]
+    def for(name:, key:, fallback_key: nil, muted: [], small: nil)
+      return [] if name.nil? || name.to_s.strip.empty?
+
+      small ||= -> { Guardrails::ModelSize.small?(name, key) }
+      small_once = memo(small)
+      seen = Set.new
+      notes = SCOPES.flat_map do |scope|
+        files(scope).filter_map do |path|
+          next unless seen.add?(File.expand_path(path))
+
+          note_at(path, scope, name: name, key: key, fallback_key: fallback_key, muted: muted, small: small_once)
+        end
+      end
+      warn_sizes(notes)
+      notes
+    end
+
+    # +text+ (+scope+'s memory index) without the lines naming a model note
+    # that loads for some model (its file in +scope+ has a `models:` line);
+    # the same object when it names none. A `model_notes_*` memory that
+    # isn't one keeps its line, so it doesn't vanish. +env+: the XDG env
+    # the scope's dir resolves from.
+    def filter_index(text, scope, env: ENV)
+      return text if text.nil? || !text.include?(PREFIX)
+
+      dir = MemoryPaths.scope_dir(scope, env: env)
+      names = files_in(dir).map { |path| File.basename(path) }
+      text.each_line.reject do |line|
+        name = MutedMemories.index_line_name(line).to_s
+        name.start_with?(PREFIX) && !name.include?(".") && names.include?("#{name}.md") &&
+          note_file?(File.join(dir, "#{name}.md"))
+      end.join
+    end
+
+    # Whether +path+ is a model note's file: it has a models: first line.
+    def note_file?(path)
+      File.file?(path) && !ModelMatch.models_line(File.open(path, encoding: "UTF-8", &:gets)).nil?
+    rescue StandardError
+      false
+    end
+
+    # Forgets which warnings were given (specs).
+    def reset_warnings!
+      @warn_mutex.synchronize { @warned.clear }
+    end
+
+    def files(scope) = files_in(MemoryPaths.scope_dir(scope))
+
+    # The `model_notes_*.md` files in +dir+, by their names on disk: the
+    # prefix exactly as written (a case-insensitive disk's glob matches
+    # MODEL_NOTES_x.md too, which the guardrails would not see as a note).
+    def files_in(dir)
+      Dir.glob(File.join(dir, "#{PREFIX}*.md")).select { |path| File.basename(path).start_with?(PREFIX) }.sort
+    rescue StandardError
+      []
+    end
+
+    def note_at(path, scope, name:, key:, fallback_key:, muted:, small:)
+      stem = File.basename(path, ".md")
+      return nil if dotted?(path, stem)
+      return nil if MutedMemories.muted?(stem, muted)
+
+      entries = models_of(path)
+      return nil unless entries
+      return nil unless ModelMatch.match?(entries, name: name, key: key, small: small)
+
+      body = File.read(path, encoding: "UTF-8").sub(/\A[^\n]*\n?/, "").strip
+      return nil if body.empty?
+
+      body = with_overlay(body, stem, scope, [key, fallback_key])
+
+      Note.new(name: stem, scope: scope, body: body, chars: body.length, digest: Digest::SHA256.hexdigest(body)[0, 12])
+    rescue StandardError
+      nil
+    end
+
+    # The note's model overlay appended as memory_read appends one: the
+    # key's, else the fallback key's. The file is read by its own path, not
+    # by name through memory_read (whose names are comma lists).
+    def with_overlay(body, stem, scope, keys)
+      keys.compact.each do |overlay_key|
+        overlay = ModelOverlay.overlay_path_for(stem, overlay_key, scope)
+        next unless overlay && File.file?(overlay)
+
+        return "#{body}#{Tools::MemoryRead::SEPARATOR}Model-specific guidance (#{overlay_key}):\n" \
+               "#{File.read(overlay, encoding: "UTF-8").strip}"
+      end
+      body
+    end
+
+    # A model overlay of a note (`model_notes_a.<key>.md`) is read with
+    # its note; any other dotted name is skipped with a warning (memory_write
+    # refuses it: next to a base it would read as an overlay).
+    def dotted?(path, stem)
+      return false unless stem.include?(".")
+
+      unless ModelOverlay.overlay_file?(path)
+        warn_once("model_note_skipped", "Warning: model note #{path} skipped: a model note's name has no dot " \
+                                        "(rename it, e.g. #{Tools::MemoryWrite.undotted(stem)}.md)", path)
+      end
+      true
+    end
+
+    # The entries of the file's `models:` first line; nil (warned once)
+    # without one.
+    def models_of(path)
+      entries = ModelMatch.models_line(File.open(path, encoding: "UTF-8", &:gets))
+      return entries if entries
+
+      warn_once("model_note_skipped", "Warning: model note #{path} skipped: its first line must be " \
+                                      "`models: <glob>|small|…`", path)
+      nil
+    end
+
+    def warn_sizes(notes)
+      notes.each do |note|
+        next unless note.chars > NOTE_LIMIT
+
+        warn_once("model_notes_large", "Warning: model note #{note.name} (#{note.scope}) is #{note.chars} chars, over " \
+                                       "#{NOTE_LIMIT}: it is sent with every request", note.name)
+      end
+      total = notes.sum(&:chars)
+      return unless total > TOTAL_LIMIT
+
+      warn_once("model_notes_large", "Warning: the model notes for this model are #{total} chars, over #{TOTAL_LIMIT}: " \
+                                     "they are sent with every request", notes.map(&:name).join(","))
+    end
+
+    # Once per message for the process (a prompt is built again on a
+    # model switch, another thinking level, changed tools).
+    def warn_once(event, echo, memory)
+      first = @warn_mutex.synchronize { @warned.add?(echo) }
+      Log.warn(:memory, event, echo: echo, memory: memory) if first
+    end
+
+    def memo(callable)
+      value = nil
+      known = false
+      lambda do
+        unless known
+          value = callable.call
+          known = true
+        end
+        value
+      end
+    end
+
+    private_class_method :note_file?, :files, :files_in, :note_at, :with_overlay, :dotted?, :models_of, :warn_sizes, :warn_once, :memo
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -94,7 +94,7 @@ module Samagotchi
     # @return [Hash]
     def stop_facts(result)
       case status(result)
-      when "failed" then { error_kind: result.error_kind, retryable: result.retryable }.compact
+      when "failed" then { error_kind: result.error_kind, retryable: result.retryable, kept_steps: result.kept_steps }.compact
       when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
       else {}
       end
@@ -242,7 +242,7 @@ module Samagotchi
 
     def no_reply_line(result, session_id = nil)
       case result.outcome
-      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
+      when "failed" then failed_line(result)
       when "canceled" then "the turn was canceled"
       when "completed" then "the turn ended with no visible answer"
       when "not_continued" then "the turn was not continued (Stop); its work so far stays"
@@ -253,6 +253,16 @@ module Samagotchi
       end
     end
 
+    # A failed turn's line; one whose work stayed says so, so the task isn't
+    # sent again over what it changed.
+    def failed_line(result)
+      why = result.text.to_s.strip
+      steps = result.kept_steps
+      return why.empty? ? "the turn failed" : "the turn failed: #{why}" unless steps.is_a?(Integer)
+
+      "the turn failed after #{steps} tool step#{"s" if steps != 1}#{": #{why}" unless why.empty?}; its work so far stays"
+    end
+
     def first_line(text)
       text.to_s.strip.lines.first.to_s.strip
     end

data/lib/samagotchi/plugin/context.rb

@@ -20,12 +20,13 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ (the session's resolved model ref, live after /model) and
-    # +state_dir+ are what ctx.sessions forks with; +model_key+ is the
+    # +state_dir+ are what ctx.sessions forks with, and +llm_context+ (the
+    # session's own LLMContextOverride, nil without one), which a fork copies; +model_key+ is the
     # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :steer, :stop_turn, :stop_generation,
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :llm_context, :steer, :stop_turn, :stop_generation,
                       keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or

data/lib/samagotchi/plugin/sessions.rb

@@ -32,6 +32,7 @@ module Samagotchi
       # Start a child session from +messages+ (usually ctx.messages plus
       # more). With no prompt the child waits idle for the user; with one it
       # runs it as its first turn, and counts against session.max_children.
+      # It keeps this session's own llm_context values (Session#llm_context).
       # Each image a message names is copied into the child, or dropped with
       # a note in its message when its file is gone.
       # @param messages [Array<Hash>] the child's conversation to start with
@@ -52,7 +53,8 @@ module Samagotchi
         child = SessionManager.spawn_session(
           prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
           parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, title: title,
-          images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir
+          images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir,
+          llm_context: @host.llm_context&.call
         )
         child.id
       end

data/lib/samagotchi/reply_wait.rb

@@ -45,7 +45,7 @@ module Samagotchi
     #   decided the outcome loaded it (a caller's next baseline); nil for
     #   :canceled and :timeout
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :session, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, keyword_init: true)
 
     module_function
 
@@ -171,8 +171,8 @@ module Samagotchi
         return Result.new(status: :no_reply, outcome: "exhausted", limit: last["limit"], session: session)
       end
 
-      text = outcome == "failed" ? failure_summary(session.messages) : nil
-      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by").transform_keys(&:to_sym) : {}
+      text = outcome == "failed" ? TurnNote.failure_summary(session.messages) : nil
+      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by", "kept_steps").transform_keys(&:to_sym) : {}
       Result.new(status: :no_reply, outcome: outcome, text: text, session: session, **why)
     end
 
@@ -200,20 +200,6 @@ module Samagotchi
       session
     end
 
-    # The summary in the failed-turn note at the conversation's tail, nil
-    # without one.
-    def failure_summary(messages)
-      list = Array(messages)
-      index = TurnNote.trailing_index(list)
-      return nil unless index
-
-      text = (list[index][:content] || list[index]["content"]).to_s
-      prefix = "#{TurnNote::OPEN}#{TurnNote::FAILED}"
-      return nil unless text.start_with?(prefix)
-
-      text[prefix.length..].sub(/\. [^.]*\.\]\z/, "")
-    end
-
     # @return [Result, nil] :done with the newest reply past the cursor
     def reply_past(id, state_dir:, cursor:)
       file = newest_reply(id, state_dir: state_dir)

data/lib/samagotchi/self_report.rb

@@ -20,6 +20,7 @@ require_relative "hooks/loader"
 require_relative "memory_bundle/provenance"
 require_relative "memory_bundle/manifest"
 require_relative "memory_bundle/system_bundle"
+require_relative "memory_bundle/index_size"
 require_relative "desktop"
 require_relative "live_versions"
 require_relative "web/lan"
@@ -53,6 +54,7 @@ module Samagotchi
         ["hooks dir", hooks_dir(env)],
         ["memories", Tools::MemoryRead.memories_dir("system", env: env)],
         ["project memories", Tools::MemoryRead.memories_dir("project", env: env)],
+        ["memory index", memory_index_summary(env)],
         ["sessions", Session.default_state_dir(env: env)],
         ["log", log_path(env)],
         ["model", model ? model_label(model, default, env) : "(not configured)"],
@@ -100,6 +102,19 @@ module Samagotchi
       LogPath.resolve(env: env) || "(disabled: log.disable)"
     end
 
+    # "system ~2.0k tokens (54 lines), project ~1.4k tokens (35 lines)":
+    # the two indexes every prompt carries (before a session's mutes), a
+    # scope over memory.index_warn_tokens marked so. Two file reads. The
+    # indexes come from +env+'s memories dirs; the limit and
+    # context.chars_per_token from Config, which reads the process's ENV
+    # and config.yml as the rest of chi self's settings (web.port) do.
+    def memory_index_summary(env)
+      limit = MemoryBundle::IndexSize.warn_limit
+      %w[system project].map { |scope| MemoryBundle::IndexSize.of_scope(scope, env: env).summary(limit) }.join(", ")
+    rescue StandardError => e
+      "(unreadable: #{e.message})"
+    end
+
     def with_presence(path)
       File.exist?(path) ? path : "#{path} (missing)"
     end

data/lib/samagotchi/send_command.rb

@@ -33,7 +33,7 @@ module Samagotchi
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
-             chi send --new [--dir DIR] [--model M] [-m TEXT] [--image PATH]...
+             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --wait [--timeout S] [--format json] ID
         Sends a message to each session, as if typed in it: a turn starts,
@@ -53,6 +53,9 @@ module Samagotchi
         --dir DIR   (--new) its folder, the project it belongs to; default
                     the current one
         --model M   (--new) its model; default the configured one
+        --llm-context LAYERS, --llm-context-apply RULE, --llm-context-budget N
+                    (--new) its own LLM context strategy (none, stale,forget),
+                    apply rule and budget (64k, off), as chi takes them
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
                     answer from you: the question, its options and the
@@ -81,6 +84,9 @@ module Samagotchi
       f.switch "--new"
       f.value "--dir"
       f.value "--model"
+      f.value "--llm-context", key: :llm_strategy
+      f.value "--llm-context-apply", key: :llm_apply
+      f.value "--llm-context-budget", key: :llm_budget
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.value "--timeout"
@@ -200,14 +206,27 @@ module Samagotchi
       return new_options(options) if options[:new]
 
       %i[dir model].each { |key| return usage_error("--#{key} needs --new") if options[key] }
+      LLM_CONTEXT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") if options[key] }
       return usage_error("give session ids") if options[:ids].empty?
 
       options
     end
 
+    # The --llm-context* option keys, and their fields.
+    LLM_CONTEXT_FLAGS = { llm_strategy: "--llm-context", llm_apply: "--llm-context-apply",
+                          llm_budget: "--llm-context-budget" }.freeze
+    LLM_CONTEXT_FIELDS = { llm_strategy: :strategy, llm_apply: :apply, llm_budget: :budget_tokens }.freeze
+
     def new_options(options)
       return usage_error("--new takes no session ids: it starts one session") unless options[:ids].empty?
 
+      words = LLM_CONTEXT_FIELDS.filter_map { |key, field| [field, options[key]] if options[key] }.to_h
+      begin
+        options[:llm_context] = LLMContextOverride.update(nil, words) unless words.empty?
+      rescue ArgumentError => e
+        return usage_error(e.message)
+      end
+
       if options[:dir]
         options[:dir] = File.expand_path(options[:dir])
         return usage_error("no folder #{options[:dir]}") unless File.directory?(options[:dir])
@@ -246,7 +265,8 @@ module Samagotchi
       begin
         start = through_worker ? { prompt: nil, title: prompt } : { prompt: prompt }
         session = SessionManager.spawn_session(**start, working_directory: options[:dir],
-                                                        model_name: options[:model], state_dir: @state_dir)
+                                                        model_name: options[:model], llm_context: options[:llm_context],
+                                                        state_dir: @state_dir)
       rescue StandardError => e
         error_line("chi send: could not start a session: #{e.message}")
         return 1

data/lib/samagotchi/session.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require_relative "atomic_file"
 require_relative "context_note"
+require_relative "llm_context_override"
 
 require_relative "paths"
 require_relative "project_scope"
@@ -70,6 +71,26 @@ module Samagotchi
     # delegate children's reports (ChildReports); context: one an attached
     # context source's change started (Worker).
     attr_accessor :last_turn
+    # The session's own llm_context values (LLMContextOverride: strategy,
+    # apply rule, budget), before the model's; nil when it has none.
+    # Saved, so a --resume and a respawned worker keep them; a plugin's
+    # fork copies them, a delegate child starts without.
+    attr_reader :llm_context
+
+    # @param value [LLMContextOverride, Hash, nil] an empty one is nil; a
+    #   file's Hash keeps the fields it can't read (LLMContextOverride.unread),
+    #   saved back as they were until the session sets its own
+    def llm_context=(value)
+      @llm_context_unread = LLMContextOverride.unread(value)
+      @llm_context = LLMContextOverride.from_file(value)
+    end
+
+    # The session file's "llm_context": the override's fields over the ones
+    # it couldn't read; nil when there are none.
+    def llm_context_file
+      saved = @llm_context_unread.merge(@llm_context&.to_file || {})
+      saved.empty? ? nil : saved
+    end
 
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise. Both strings
@@ -97,7 +118,7 @@ module Samagotchi
                    first_preview: "", test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
-                   last_turn: nil, model_typed: nil, delegate: false)
+                   last_turn: nil, model_typed: nil, delegate: false, llm_context: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -120,6 +141,7 @@ module Samagotchi
       @scratch = !!scratch
       @last_turn = last_turn
       @delegate = !!delegate
+      self.llm_context = llm_context
       @archived = false
     end
 
@@ -170,7 +192,7 @@ module Samagotchi
     #   seed); [] by default
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
                          preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
-                         scratch: false, model_typed: nil, delegate: false)
+                         scratch: false, model_typed: nil, delegate: false, llm_context: nil)
       now = Time.now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?
@@ -194,7 +216,8 @@ module Samagotchi
         muted_memory_names: muted_memory_names,
         parent_id: parent_id,
         scratch: scratch,
-        delegate: delegate
+        delegate: delegate,
+        llm_context: llm_context
       )
     end
 
@@ -249,7 +272,8 @@ module Samagotchi
       "parent_id" => nil,
       "scratch" => false,
       "last_turn" => nil,
-      "delegate" => false
+      "delegate" => false,
+      "llm_context" => nil
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -368,6 +392,7 @@ module Samagotchi
                 when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
+                when "llm_context" then llm_context_file
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")

data/lib/samagotchi/session_commands.rb

@@ -9,10 +9,11 @@ require_relative "tools/builtins"
 require_relative "tools/context_read"
 require_relative "tools/peers"
 require_relative "commands/registry"
+require_relative "llm_context_command"
 
 module Samagotchi
   # The session commands a REPL and a session worker both run: /model,
-  # /models, /guardrails, /context, !rollback, !cmd and the answer to a continue offer. They act on
+  # /models, /llm-context, /guardrails, /context, !rollback, !cmd and the answer to a continue offer. They act on
   # the Engine and its TurnFlow; the host prints the result's output and
   # runs a continue turn when asked to (#run never runs a turn).
   #
@@ -26,6 +27,7 @@ module Samagotchi
     GUARDRAILS_COMMAND = "/guardrails"
     CONTEXT_COMMAND = "/context"
     HELP_COMMAND = "/help"
+    LLM_CONTEXT_COMMAND = LLMContextCommand::NAME
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
     MODELS_PER_HOST = 20
@@ -73,6 +75,9 @@ module Samagotchi
       end
       registry.register(MODEL_COMMAND, "show or switch the model",
                         match: ->(text) { text.match?(%r{\A/model(?:\s+.*)?\z}) }) { |text| model(text) }
+      # Not anytime: it saves the session; it takes effect at the next turn's start.
+      registry.register(LLM_CONTEXT_COMMAND, "show or set this session's LLM context strategy, apply rule and budget",
+                        id: :llm_context, match: ->(text) { text.match?(%r{\A/llm-context(?:\s+.*)?\z}) }) { |text| llm_context(text) }
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
@@ -330,6 +335,21 @@ module Samagotchi
       @save.call(session)
     end
 
+    # /llm-context (LLMContextCommand); :llm_context in changed when it set
+    # the session's values.
+    def llm_context(text)
+      output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_llm_context(session) })
+                                         .run(text.delete_prefix(LLM_CONTEXT_COMMAND))
+      reply(output, changed: changed ? [:llm_context] : [])
+    rescue ArgumentError => e
+      reply(e.message, status: :error)
+    end
+
+    def save_llm_context(session)
+      @engine.store_model!(session)
+      @save.call(session)
+    end
+
     def model(text)
       output, switched = model_command(text)
       reply(output, changed: switched ? [:model] : [])

data/lib/samagotchi/session_manager.rb

@@ -129,11 +129,13 @@ module Samagotchi
     # @param images_from [String, nil] the session dir the seed's images are in
     # @param title [String, nil] what the lists show before the first turn
     #   (the prompt's preview by default, else the seed's first user message)
+    # @param llm_context [LLMContextOverride, nil] the session's own
+    #   llm_context values (chi --llm-context; a fork copies its parent's)
     # @return [Session] with #seed_images_dropped: refs whose file was gone,
     #   and #model_warning: an id its host's saved list doesn't have
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
-                           title: nil, delegate: false)
+                           title: nil, delegate: false, llm_context: nil)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
       # alias is retargeted), with the name as typed beside it. A wrong host
@@ -153,7 +155,8 @@ module Samagotchi
         muted_memory_names: muted_memories,
         parent_id: parent_id,
         messages: messages,
-        delegate: delegate
+        delegate: delegate,
+        llm_context: llm_context
       )
       session.model_warning = model_warning
       # With no prompt there is no first turn to run (an attaching UI sends

data/lib/samagotchi/session_metrics.rb

@@ -53,8 +53,14 @@ module Samagotchi
     # had none) and the session's tokens block as the snapshot has it.
     GenerationReport = Data.define(:speed, :tokens)
 
-    SavedSummary = Data.define(:ctx_pct, :prompt_sum, :completion_sum, :cached_sum, :reasoning_sum, :cost_sum) do
-      def tokens = to_h.except(:ctx_pct)
+    # memory_index: the memory indexes the session's prompt held
+    # ({ system: { tokens:, lines: }, project: … }, string keys as saved),
+    # nil when an older file has none.
+    SavedSummary = Data.define(:ctx_pct, :prompt_sum, :completion_sum, :cached_sum, :reasoning_sum, :cost_sum,
+                               :memory_index) do
+      def initialize(memory_index: nil, **) = super
+
+      def tokens = to_h.except(:ctx_pct, :memory_index)
     end
 
     # Per-turn transient state, reset on each turn_started.
@@ -150,7 +156,8 @@ module Samagotchi
       count = ->(key) { tokens[key].is_a?(Numeric) ? tokens[key] : 0 }
       SavedSummary.new(ctx_pct: saved_pct(data["context"]), prompt_sum: count.call("prompt_sum"),
                        completion_sum: count.call("completion_sum"), cached_sum: count.call("cached_sum"),
-                       reasoning_sum: count.call("reasoning_sum"), cost_sum: count.call("cost_sum"))
+                       reasoning_sum: count.call("reasoning_sum"), cost_sum: count.call("cost_sum"),
+                       memory_index: data["memory_index"].is_a?(Hash) ? data["memory_index"] : nil)
     rescue JSON::ParserError, SystemCallError, TypeError
       nil
     end
@@ -196,6 +203,7 @@ module Samagotchi
       @wall_clock = wall_clock || -> { Time.now }
       @session_id = nil
       @state_dir = nil
+      @memory_index = nil
       @started_at = nil
       @last_activity_at = nil
       @turn = nil
@@ -217,6 +225,14 @@ module Samagotchi
       end
     end
 
+    # The memory indexes the session's prompt holds (SystemPrompt#memory_index:
+    # { system: { tokens:, lines: }, project: … }), set by the Engine when
+    # it builds the prompt it sends; the snapshot and analytics.json carry it.
+    # @param block [Hash, nil]
+    def memory_index=(block)
+      @mutex.synchronize { @memory_index = block if block }
+    end
+
     # The sessions dir analytics.json is read from and saved to (nil: the
     # XDG default). Set it before #session_id=.
     attr_writer :state_dir
@@ -367,6 +383,7 @@ module Samagotchi
         cancellations: totals[:cancellations],
         tokens: tokens_block(totals, turn),
         context: context_block(@turn_records),
+        memory_index: @memory_index,
         profile: @profile,
         profile_source: @profile_source,
         served_model: @served_model,
@@ -875,6 +892,8 @@ module Samagotchi
         @served_model = prior["served_model"]
         @served_model_for = prior["served_model_for"]
       end
+      # The indexes the prompt last held, until this process builds its own.
+      @memory_index ||= symbolized(prior["memory_index"]) if prior["memory_index"].is_a?(Hash)
       # The window last seen, until this process's first generation reports.
       window = prior["context"].is_a?(Hash) ? prior["context"] : {}
       if window["window_tokens"] && @context_window_tokens.nil?
@@ -885,6 +904,10 @@ module Samagotchi
       nil
     end
 
+    def symbolized(hash)
+      hash.to_h { |key, value| [key.to_sym, value.is_a?(Hash) ? symbolized(value) : value] }
+    end
+
     def loaded_records(records)
       Array(records).filter_map { |record| record.transform_keys(&:to_sym) if record.is_a?(Hash) && record["id"] }
     end