samagotchi 0.40.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c41a6466e51c4da290f55cca9398a3221def773f8ee3235102e97322030c882
-  data.tar.gz: 86bc79ce21478e0420e82fc47307fdf9934bee4a2642cda3c8bbf1c26a248c7e
+  metadata.gz: d41b91ef2514e877a756d7f66ba02f58b65c7d85f7446728b02ec06f652299b3
+  data.tar.gz: 37e0869508863e5db69395b847ac147101f60a79208a5ba9e789e3427eb9716e
 SHA512:
-  metadata.gz: 52bf3393d2a7ff228aba277aa7fea67b4f82619578ba25d28c061e2256c8ef9a36698a250ca928c1916a3ba7a19ffef56fd8eeda7c232d37661fcd1188d63895
-  data.tar.gz: 40d4c0006a4ac0a9d07072f09d691169d7c8d765eed4be45ff2c0ff5acdb04d5dc2ff20e009429abbdd54822d4a91e212f8efbbca75b43f0671382a1fcf16768
+  metadata.gz: abb02fdd05aec927500fbb42a750b9da3dc9e1c8e24cbc55bfdc933e797e206ee8e3a3502d0a4074804b0342f856726d2b04d2eb15c2aa61682e23439bca38ea
+  data.tar.gz: 681406d11e96949fd168b252a6717fe2f6dcfaa765400bf66a43a7131dc4440ff7f077312f3ccd219ddce8c05e88f15e4bc808c52652d265beed59eed89c8c1c

data/CHANGELOG.md

@@ -8,6 +8,85 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-08
+
+### Added
+
+- Which model notes a session's prompt carried: each prompt build (and `/model`) records them in the session file
+  (`prompt_notes`: name, scope, size and a short digest), and they are shown in `/stats` (`model notes:
+  model_notes_deepseek (system, 612 chars)`), at the end of `/model`'s line (`; notes: …`, after a switch the new
+  model's), as a `notes: deepseek` chip in the web's info bar and as a `model notes` row in `chi self`. Nothing shows
+  without notes. See [docs/memory.md](docs/memory.md) ("Model notes").
+- For development: `script/model_notes_report.rb`, which groups stored sessions by model and by the model notes
+  their prompt carried and compares the calls to the first edit and commit, commits per 100 steps, bare `&` in
+  `execute`, the longest run without an edit and the Continues and steers each session needed (`--model`,
+  `--since`, `--min-steps`, `--json`). It isn't part of the gem. See [docs/testing.md](docs/testing.md).
+
+### Fixed
+
+- The web showed no failure line after a reload for a failed turn whose steps stayed (new in 0.41.0), so the turn
+  looked unfinished; it ends with the same `✕ turn failed: <why>; partial progress kept (!rollback restores the
+  pre-turn state)` line as live (from the turn record, which keeps the failure now; a turn recorded before this
+  shows none).
+- A delegate report could reach the parent's model twice: a reminder or continue turn that failed before any
+  progress kept the report it had read, and the next turn brought it again. A canceled continue turn's report was
+  never delivered. A report's ring now goes only when the turn that read it stays in the conversation.
+- `/llm-context` (the web's `llm ctx` chip, `--llm-context` on `--attach`) against a worker on an older chi answered
+  `400 not a session command`; the web (`501 not_supported`) and the attached terminal say the worker runs an older
+  chi, with the line that restarts it.
+
+## [0.41.0] - 2026-10-08
+
+### Added
+
+- Model notes: a memory named `model_notes_<name>` whose first line is `models: <globs>|small` goes into the system
+  prompt of every session on a matching model, in its own section after the identity memory (all matching notes,
+  system scope then project). The habits of one model (or a family, or every small model) no longer ride on an
+  identity overlay keyed to one provider's id. `--mute model_notes_<name>` drops one for a session; `memory_write`
+  refuses a note without the `models:` line. See [docs/memory.md](docs/memory.md) ("Model notes").
+- The guardrails bundle (0.9.0) asks, once at a time and only the user may allow it, before a model writes a memory
+  that reaches the system prompt: the identity memory, a model note or an overlay of either, by `memory_write`,
+  `write` or `edit`, through a symlink or in any case of the name (`prompt-memory-write`), or a model overlay of any
+  memory (`model-overlay-write`). A rule's `memory:` takes `overlay` and `prompt`. Run `chi update` to get it.
+- A session's own LLM context strategy, apply rule and budget, before the model's: `chi --llm-context stale,forget
+  --llm-context-apply turn_end --llm-context-budget 64k` at start (also `chi send --new`, and `--resume`),
+  `/llm-context` in the session (no arguments: each value and where it came from; `strategy`, `apply`, `budget`,
+  `default` to unset one, `reset`), and the web's `llm ctx` chip in the info bar. Saved with the session (kept by
+  `--resume` and forks, not by delegates); a change applies from the next turn's start, and its reply says what it
+  costs (forget on or off re-reads the prompt once; stale turned on stages the reads already superseded as one
+  batch; a layer turned off sends its stubs whole again). `/stats` and the turn log show the effective strategy and
+  its source. See [docs/configuration.md](docs/configuration.md) ("LLM context: a session's own strategy").
+- The memory indexes' size, which every prompt carries in full: `chi self` has a `memory index` row (`system ~2.0k
+  tokens (54 lines), project ~1.4k tokens (35 lines)`), and `/stats` and the web's ctx tooltip show what the
+  session's prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`). A
+  `memory_write`, `write` or `edit` that takes a scope's index over `memory.index_warn_tokens` (new; default 2500 per
+  scope, `0` off) gets one note asking the model to tighten long index descriptions when it has a moment, and not to
+  remove or merge memories unless the user asks; a write while already over gets none. See
+  [docs/memory.md](docs/memory.md) ("The index's size").
+
+### Changed
+
+- A guardrails rule's `models:` also takes a `|`-separated string (`"small|deepseek-*"`), as
+  `guardrails.small_models` does.
+- The system prompt's `Model:` line says guidance for this model goes in a model note (it said a memory overlay).
+- `memory_write` refuses a memory name with a comma (`memory_read` reads a comma list of names).
+
+### Fixed
+
+- A turn that failed partway (out of credits, a server error, any provider error but a context overflow) after tool
+  calls lost them: the saved session held only the failure note, and the prompt went back for a retry that would
+  run the task again over files it had already changed. Such a turn now keeps its steps, as a cancel does: the model
+  reads that it failed after N tool steps and that its work stays, the prompt is not handed back, and `!rollback`
+  still erases the turn (`partial progress kept` in the terminal and on the web; `chi send --wait` and a delegating
+  parent read `the turn failed after N tool steps: <why>; its work so far stays`). A turn that failed before it got
+  anywhere, or on a context overflow (kept, the conversation would stay too long for the window), is rolled back and
+  its prompt restored, as before. Since 0.2.0.
+- On a case-insensitive disk a write to the memories' `INDEX.md` (any case) was taken for a memory and added a bogus
+  line to the index.
+
+Update with `chi update`: it updates guardrails (0.9.0: asks before a model writes a memory that reaches the system
+prompt; needs chi 0.41.0).
+
 ## [0.40.0] - 2026-10-08
 
 ### Added
@@ -1903,7 +1982,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.40.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.42.0...HEAD
+[0.42.0]: https://github.com/dm1try/samagotchi/compare/v0.41.0...v0.42.0
+[0.41.0]: https://github.com/dm1try/samagotchi/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/dm1try/samagotchi/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/dm1try/samagotchi/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/dm1try/samagotchi/compare/v0.37.0...v0.38.0

data/README.md

@@ -200,7 +200,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 
 - [CLI and REPL](docs/cli.md): flags, sharing a session, web UI, `/model`, status line
 - [Configuration](docs/configuration.md): `config.yml`, hosts, model server transports, timeouts, retries, logs
-- [Memory](docs/memory.md): scopes and model-specific overlays
+- [Memory](docs/memory.md): scopes, model-specific overlays and model notes
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
 - [Attached context](docs/context.md): `chi context`, sources, scopes, waking, the github-pr bundle, safety
 - [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, triage, what a session gets, the triage log

data/bin/chi

@@ -82,7 +82,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -120,6 +120,10 @@ parser = OptionParser.new do |opts|
                               "sessions already running keep theirs) [env SAMAGOTCHI_THINKING_LEVEL]") { |l| cli_overrides["thinking.level"] = l }
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
   opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
+  opts.on("--llm-context LAYERS", "This session's own LLM context strategy: none, or layers such as stale,forget (saved in the session, " \
+                                 "before the model's; /llm-context changes it)") { |v| (options[:llm_context] ||= {})[:strategy] = v }
+  opts.on("--llm-context-apply RULE", "This session's own apply rule for it: payoff|next_request|turn_end") { |v| (options[:llm_context] ||= {})[:apply] = v }
+  opts.on("--llm-context-budget TOKENS", "This session's own context budget: tokens (64000, 64k) or off") { |v| (options[:llm_context] ||= {})[:budget_tokens] = v }
   opts.on("--no-interrupt", "Raise the tool call limit to 1000 iterations (useful for long tasks)") { options[:no_interrupt] = true; cli_overrides["no_interrupt"] = true }
   opts.on("--non-interactive", "Run a single prompt and exit (no REPL, implies --no-interrupt)") { options[:non_interactive] = true }
   opts.on("-v", "--verbose", "Print raw LLM responses and tool calls/results (runs a plain REPL, not attached)") { options[:verbose] = true }
@@ -286,6 +290,17 @@ if options[:memories] || options[:muted]
   end
 end
 
+# --llm-context*: checked here, before anything starts.
+if options[:llm_context]
+  require "samagotchi/llm_context_override"
+  begin
+    Samagotchi::LLMContextOverride.update(nil, options[:llm_context])
+  rescue ArgumentError => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+end
+
 chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
@@ -317,7 +332,8 @@ if launch == :attached
                                                        no_interrupt: !!options[:no_interrupt],
                                                        default_input: !options[:no_default_input],
                                                        memories: options[:memories] || [],
-                                                       muted_memories: options[:muted] || [])
+                                                       muted_memories: options[:muted] || [],
+                                                       llm_context: options[:llm_context] || {})
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -334,6 +350,7 @@ begin
     no_default_input: options[:no_default_input],
     memories: options[:memories] || [],
     muted_memories: options[:muted] || [],
+    llm_context: options[:llm_context] || {},
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

data/docs/cli.md

@@ -22,7 +22,7 @@
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
-- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
+- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
 
@@ -184,6 +184,9 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
+| `--llm-context LAYERS` | This session's own LLM context strategy: `none`, or layers such as `stale` or `stale,forget` (comma, space or `\|` separated). Saved in the session, before the model's `llm_context_strategy`. With `--resume` it is set on the resumed session; on an attached or resumed worker it runs as `/llm-context` before the first prompt (after `--model`'s `/model`). A value that isn't one is an error before anything starts. See "LLM context: a session's own strategy" in configuration.md. |
+| `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
+| `--llm-context-budget TOKENS` | This session's own context budget: `64000`, `64k` (4k to 10M), or `off` (wins over the model's budget). |
 | `--no-interrupt` | Raise the tool-call limit to 1000 iterations for long tasks. |
 | `--no-default-input` | Skip prefilling the first REPL line from `SAMAGOTCHI_DEFAULT_INPUT`. |
 | `-v`, `--verbose` | Log at debug level (raw LLM responses, tool call/result payloads) and print every log record to stderr too. |
@@ -337,7 +340,8 @@ note or image) is deleted as its worker exits, and `/exit` says so; set
 
 `chi sessions stop ID...` stops each session's worker and waits for it to exit, so
 a `chi --resume ID` after it starts a fresh one. A worker still running an
-older chi (from before an upgrade) takes turns but not commands; the attached
+older chi (from before an upgrade) takes turns, but not commands, or not the
+ones newer than it (`/llm-context`, `--llm-context` on `--attach`); the attached
 terminal and the Web UI say so, with that restart line.
 
 `chi sessions restart ID...` hands each session to a new worker on the newest
@@ -425,7 +429,7 @@ request (with the cached tokens, the cache writes, the re-prefilled tokens and t
 reports them),
 the decode speed, generation latency, cancellations, retries (the network's),
 thinking cuts (generations a plugin such as loop-guard cut) and output cap hits
-(generations that ended at the provider's cap), context used and window, the prompt profile and the model the server says it ran, and the
+(generations that ended at the provider's cap), context used and window, the memory indexes the session's prompt holds ([Memory](memory.md#the-indexs-size)), the model notes it carried (`model notes:      model_notes_deepseek (system, 612 chars)`, none without any; [Memory](memory.md#model-notes)), the prompt profile and the model the server says it ran, and the
 cost when the provider reports one (OpenRouter's `usage.cost`; no prices are
 guessed). The speed line is the last generation's and the session's average
 (weighted by tokens): llama.cpp reports it exactly (`87 tok/s out, 1.9k tok/s
@@ -437,6 +441,22 @@ keeps its own numbers: a parent's tokens and cost leave them out. `/recap` is in
 [Session recap](#session-recap), `/model` and `/models` in [Runtime Model
 Switch](#runtime-model-switch-assist-mode).
 
+`/llm-context` shows the LLM context strategy, apply rule and budget the next
+turn runs under, each with where it came from (`the session`, `models: <key>`,
+`hosts entry '<name>'`, `llm_context.*`), and the session's own values.
+`/llm-context strategy <none|stale|stale,forget> apply <payoff|next_request|turn_end>
+budget <tokens|64k|off>` sets the session's own (any of the three, in one line;
+`default` unsets one), and `/llm-context reset` unsets them all. A change is
+saved with the session and applies from the next turn's start; the reply says
+what it costs: `forget` on or off re-reads the whole prompt once, `stale` turned
+on stages the reads already superseded as one batch under the apply rule, and a
+layer turned off sends its stubs whole again (turning it back on brings them
+back). It runs between turns (a worker answers `busy` mid-turn). `/stats` shows
+the same values on its `llm context:` line. The web's info bar shows them as the
+`llm ctx` chip (`llm ctx stale,forget · session`), whose popover sets them
+through `/llm-context`. See "LLM context: a session's own strategy" in
+[configuration.md](configuration.md).
+
 ### Typing during a turn
 
 The prompt stays open while a turn runs, in an attached terminal and in the plain
@@ -689,7 +709,7 @@ In interactive assist mode, you can switch the request model without restarting:
 - `/model host:model` or `/model host:alias`: qualified host routing (only `:` names a host; `openai/gpt-4o` is a model id). `host:alias` applies the alias; an alias whose target names another host is refused (`alias 'tiny' names host 'box', not 'openrouter'`). Aliases apply once: an alias pointing to another alias sends that name as written.
 - `/model --default <name>`: set session model and persist as new default (`default.model`) in `config.yml` for future sessions (supports `host:model` full ref). It writes only the file: an exported `SAMAGOTCHI_DEFAULT_MODEL` (or `--model`) still wins over it.
 - `/model <name> --alias <alias>`: create alias for current effective model (alias value may be bare or `host:model`).
-- `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`).
+- `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`). When the session's prompt carries model notes the line ends with `; notes: model_notes_deepseek (system, 612 chars)`; a switch's `runtime model set to …` names the new model's ([Memory](memory.md#model-notes)).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
 - `/guardrails`: the guardrail rules (by source), what failed to load, and your stored approvals, numbered; `/guardrails revoke N` removes approval N (see [Guardrails](guardrails.md)).
 - `/models`: list model ids aggregated across all `hosts:` (an alias shows next to its id: a bare alias on every host listing the id, a `host:model` one only under its host; grouped `host (host:port):` with per-host `unreachable` warnings, e.g. an unset `api_key_env`; lists cached 60s, 10 minutes for a remote host; lazy — no startup prefill). At most 20 ids per host, then `… and N more`; `/models <text>` lists every id containing `<text>` (any case), e.g. `/models qwen` on OpenRouter.
@@ -861,9 +881,14 @@ Behavior notes:
 - Cancellation returns control to the prompt immediately; what you typed there stays.
 - The turn ends with one line, `■ turn canceled (Ctrl-C) · 3.1s` (`■`, a stop someone chose, in amber), and for a prompt turn a dim
   `partial progress kept; !rollback restores the pre-turn state` under it (a canceled continue is back where it
-  started). A failed turn ends with `✕ turn failed: <summary> · 2.0s` and a dim `prompt restored for retry`. The
-  REPL and attached mode say the same; the web says `■ canceled (Ctrl-C)` (`stopped` for its Stop button,
-  `by a hook` for a hook's). A turn a bundle's plugin stopped names it: `■ turn stopped by loop-guard` (the web:
+  started). A failed turn ends with `✕ turn failed: <summary> · 2.0s` and a dim `prompt restored for retry` when it
+  failed before it got anywhere, or on a context overflow (the conversation goes back to before it); one that got to
+  tool steps keeps them, as a cancel does, with the dim `partial progress kept; !rollback restores the pre-turn state`
+  (the model reads a note saying how many steps ran and why it stopped; `chi send --wait` and a delegating parent
+  read `the turn failed after N tool steps: <why>; its work so far stays`). The
+  REPL and attached mode say the same; the web ends a failed turn whose steps stayed with `✕ turn failed: <summary>;
+  partial progress kept (!rollback restores the pre-turn state)`, after a reload too, and says `■ canceled (Ctrl-C)`
+  (`stopped` for its Stop button, `by a hook` for a hook's). A turn a bundle's plugin stopped names it: `■ turn stopped by loop-guard` (the web:
   `■ stopped by loop-guard`).
 - Visible text the canceled request had streamed stays in the conversation, marked `[interrupted]`, so the next
   message (or a continue) picks up from the half-finished reply; the canceled request's thinking and any unfinished

data/docs/configuration.md

@@ -900,6 +900,36 @@ models:
 - `/stats` counts the re-prefilled tokens each applied batch costs; `script/llm_context_bench.rb --strategy
   forget_outputs` replays the offer on stored sessions (docs/internals/llm-context-bench.md).
 
+## LLM context: a session's own strategy
+
+A session can set its own `llm_context` strategy, apply rule and budget, which come before the model's, its host's
+and the global ones (resolution: the session, `models.<key>`, `hosts.<name>`, then `llm_context.*`; each value on
+its own). The first target is a long session such as a day-long coordinator, where `stale` pays off across many turns.
+
+- **Set it** at start with `chi --llm-context stale,forget --llm-context-apply turn_end --llm-context-budget 64k`
+  (the same flags on `chi send --new`), in the session with `/llm-context strategy … apply … budget …`
+  (docs/cli.md, "Session commands"), or from the web's `llm ctx` chip in the info bar.
+- **Values:** `none` and a budget of `off` are values the session sets on purpose (they win over the model's);
+  `default` (or `/llm-context reset` for all three) unsets one, back to following the model. A budget is 4k to
+  10M tokens (`4000`–`10000000`, or `4k`–`10000k`). The layers are kept in chi's order (`stale`, then `forget`).
+  A value in the session file chi can't read (an unknown layer) follows the model and is saved back as written.
+- **Kept:** in the session file (`llm_context`), so `--resume` and a respawned worker keep it; a plugin's fork
+  copies its parent's; a delegate child starts without one (it follows its own model).
+- **When it applies:** from the next turn's start; a running turn keeps the strategy it started with. The command
+  runs between turns, like `/model`.
+- **Switching on `stale`:** the reads the conversation already holds that a later read superseded go in as one
+  batch under the session's apply rule (`next_request`: the next request; `turn_end`: the end of the next turn;
+  `payoff`: as for any batch). `/llm-context` says how many.
+- **Switching `forget` on or off** changes the tool list (`forget_outputs`), the ids on outputs and the system
+  prompt: the next request re-reads the whole prompt once (a full cache break). Turned off, its past `forget_outputs` calls
+  and their results stay in the history.
+- **Switching a layer off:** its stubs go out whole again from the next request (a cache break from the first). The
+  session keeps the originals and the edits, so turning the layer back on brings the same stubs back.
+- **Where to see it:** `/llm-context` (each value and where it came from: `the session`, `models: <key>`,
+  `hosts entry '<name>'`, `llm_context.*`), `/stats` (`llm context:`), the turn log (an `llm_context` record per
+  turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts
+  its saved context against the session's budget.
+
 ## All settings
 
 Every setting below takes the three forms described in
@@ -962,16 +992,17 @@ described in their own sections.
 | `context.status` | `true` | yes | Context-usage telemetry for the model. See [context telemetry](internals/context-telemetry.md). |
 | `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. `models.<key>.window_tokens` and `hosts.<name>.window_tokens` come first; see "The context window". |
 | `models.<key>.window_tokens`, `hosts.<name>.window_tokens` | none | | A model's or host's context window when the server and its model list report none. |
-| `llm_context.strategy` | `none` | | What the model is sent of the conversation: `none` (everything, unchanged), or a list of layers (`stale`, `forget`; `"\|"`-separated or a YAML list). `stale`: a file read that a later read covering its lines superseded (a read that came back whole: not the head/tail preview of a big file, nor cut at `max_tool_output_chars`) is sent as a stub (`[read] lib/x.rb lines 1-200: superseded by a later read`). With `llm_context.stale_edits: true` (opt-in, experimental) so is a read a later successful edit or write of the file superseded (`superseded by a later edit`); on the replay bench these stubs cost about 5x the tokens they free in re-prefill, and 26% of them were needed again (against a 6% base rate). No read of a file edited or written in the last `llm_context.protect_steps` steps is stubbed. When stubs reach the prompt is `llm_context.apply`: `next_request` sends a read a later read superseded from the next request, and an edit-driven stub at the end of a turn the model answered; `turn_end` sends them all at the end of a turn the model answered (a turn that ran out of steps keeps them staged; on the native loop against a local llama.cpp the turn-end warm-up prefills the edited prompt, elsewhere the next turn's first request carries the cache break); `payoff` sends the batch at a request when the tokens it frees are at least the tail after its earliest stub (what the server reads again), or the context is in the top `context.status_thresholds` bucket (which needs `context.status` on), else at the end of a turn the model answered. A re-read's tail holds the later read, so in practice payoff usually waits for the turn's end. Each batch breaks the prompt cache from its earliest stub; `/stats` counts the re-prefilled tokens. The session keeps the outputs and the stubs it sent, so a `--resume` sends the same. `forget` (experimental) offers the model the `forget_outputs` tool; see "LLM context: the forget layer". An unknown name warns and is `none`. `models.<key>.llm_context_strategy` and `hosts.<name>.llm_context_strategy` come first. |
+| `llm_context.strategy` | `none` | | What the model is sent of the conversation: `none` (everything, unchanged), or a list of layers (`stale`, `forget`; `"\|"`-separated or a YAML list). `stale`: a file read that a later read covering its lines superseded (a read that came back whole: not the head/tail preview of a big file, nor cut at `max_tool_output_chars`) is sent as a stub (`[read] lib/x.rb lines 1-200: superseded by a later read`). With `llm_context.stale_edits: true` (opt-in, experimental) so is a read a later successful edit or write of the file superseded (`superseded by a later edit`); on the replay bench these stubs cost about 5x the tokens they free in re-prefill, and 26% of them were needed again (against a 6% base rate). No read of a file edited or written in the last `llm_context.protect_steps` steps is stubbed. When stubs reach the prompt is `llm_context.apply`: `next_request` sends a read a later read superseded from the next request, and an edit-driven stub at the end of a turn the model answered; `turn_end` sends them all at the end of a turn the model answered (a turn that ran out of steps keeps them staged; on the native loop against a local llama.cpp the turn-end warm-up prefills the edited prompt, elsewhere the next turn's first request carries the cache break); `payoff` sends the batch at a request when the tokens it frees are at least the tail after its earliest stub (what the server reads again), or the context is in the top `context.status_thresholds` bucket (which needs `context.status` on), else at the end of a turn the model answered. A re-read's tail holds the later read, so in practice payoff usually waits for the turn's end. Each batch breaks the prompt cache from its earliest stub; `/stats` counts the re-prefilled tokens. The session keeps the outputs and the stubs it sent, so a `--resume` sends the same. `forget` (experimental) offers the model the `forget_outputs` tool; see "LLM context: the forget layer". An unknown name warns and is `none`. A session's own (`chi --llm-context`, `/llm-context`; "LLM context: a session's own strategy"), then `models.<key>.llm_context_strategy` and `hosts.<name>.llm_context_strategy` come first. |
 | `models.<key>.llm_context_strategy`, `hosts.<name>.llm_context_strategy` | none | | A model's or host's `llm_context.strategy`. |
-| `llm_context.apply` | `payoff` | | When a layer's edits reach the prompt (each batch breaks the prompt cache from its earliest edit): `payoff`, `next_request` or `turn_end`. An unknown value warns and is `payoff`. `models.<key>.llm_context_apply` and `hosts.<name>.llm_context_apply` come first. |
+| `llm_context.apply` | `payoff` | | When a layer's edits reach the prompt (each batch breaks the prompt cache from its earliest edit): `payoff`, `next_request` or `turn_end`. An unknown value warns and is `payoff`. A session's own (`--llm-context-apply`, `/llm-context apply`), then `models.<key>.llm_context_apply` and `hosts.<name>.llm_context_apply` come first. |
 | `models.<key>.llm_context_apply`, `hosts.<name>.llm_context_apply` | none | | A model's or host's `llm_context.apply`. |
 | `llm_context.stale_edits` | `false` | | Opt-in, experimental: `stale` also stubs a read that a later successful edit or write of the file superseded. |
 | `llm_context.protect_steps` | `3` | | `stale` never stubs a read of a file edited or written in the last N steps (tool batches; counted across the whole conversation, not only the turn). `0` turns the protection off. Under `forget`, `forget_outputs` refuses an output from the last N steps, and a read of a file edited or written in them unless the forget keeps some of its lines. |
-| `llm_context.budget_tokens` | none | | A soft context budget in tokens (e.g. `64000`); off when unset or `0`. When set, the context status buckets (`context.status_thresholds`) count against it instead of the window (the smaller of the two), so the `[CONTEXT: …]` lines, `payoff`'s top bucket and, under `forget`, the `forget_outputs` offers come under it. `models.<key>.llm_context_budget_tokens` and `hosts.<name>.llm_context_budget_tokens` come first. |
+| `llm_context.budget_tokens` | none | | A soft context budget in tokens (e.g. `64000`); off when unset or `0`. When set, the context status buckets (`context.status_thresholds`) count against it instead of the window (the smaller of the two), so the `[CONTEXT: …]` lines, `payoff`'s top bucket and, under `forget`, the `forget_outputs` offers come under it. A session's own (`--llm-context-budget`, `/llm-context budget`; `off` there wins over the model's), then `models.<key>.llm_context_budget_tokens` and `hosts.<name>.llm_context_budget_tokens` come first. |
 | `models.<key>.llm_context_budget_tokens`, `hosts.<name>.llm_context_budget_tokens` | none | | A model's or host's `llm_context.budget_tokens`. |
 | `llm_context.policy` | the subtask-boundaries line | | The sentence `forget_outputs`' description carries (the `forget` layer): "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it established; keep anything you'll still edit against." Blank: none. Read when a session starts. |
 | `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
+| `memory.index_warn_tokens` | `2500` | yes | The tokens one scope's memory index (project or system; sent with every prompt) may hold before a `memory_write`, `write` or `edit` that takes it over gets a note asking the model to tighten long index descriptions; `0`: no note. Estimated as characters / `context.chars_per_token`. `memory:` is its own section, not the `memories:` preload list. See [Memory](memory.md). |
 | `context.status_thresholds` | `20,40,60,80` | yes | Percentages that trigger a status. |
 | `context.status_cadence` | `0` | yes | Also every N rounds; `0` = thresholds only. |
 | `context.every_seconds` | `300` | | How often an attached context source's command runs when it has no `--every` (seconds, at least 30). See [Attached context](context.md). |

data/docs/guardrails.md

@@ -249,7 +249,12 @@ A rule gives at least one of `tool`, `command`, `path`, `git`, `touches`, `rm` a
 `memory: remove` matches a `memory_write` with `remove: true` (it moves a
 memory into the bundle trash). Nothing else asks about it: a memory's file is
 never outside the repo (below), so without such a rule any session, a delegate
-child included, removes a memory unasked.
+child included, removes a memory unasked. `memory: overlay` matches a
+`memory_write` of a model overlay (`current_model_only: true`). `memory:
+prompt` matches a `memory_write`, `write` or `edit` of a memory file that
+reaches the system prompt (`identity.md`, `model_notes_*.md` and their
+overlays) right in a memories folder (the system scope's or a project's),
+resolved: symlinks, `..` and the case the disk has; the name in any case.
 
 `rm: outside_tmp` (shell tools) matches a command whose `rm -r -f` reaches
 outside the tmp folders (`$TMPDIR`, `/tmp`, `/var/tmp`): every such `rm` in a
@@ -359,7 +364,9 @@ match no rule. `disable:` only removes rules; hooks and the core checks still vo
 
 `models:` makes a rule vote only for some models: `small`, or a glob on the
 model's name (`Qwen3.6-*`, matched on the bare name without the host prefix and
-on the model key `qwen3-6-27b`, case-insensitively), or a list of them. Without
+on the model key `qwen3-6-27b`, case-insensitively), or a list of them (a YAML list or
+`|`-separated, `"small|deepseek-*"`; model notes take the same grammar, see
+[Memory](memory.md#model-notes)). Without
 `models:` a rule is for every model. With no model name set, a `models:` rule
 doesn't vote.
 
@@ -452,7 +459,12 @@ once at a time and only by the user: it is the user's command, which also
 refuses to run inside a session; see [Broadcast](broadcast.md)); removing a
 memory with `memory_write remove: true` (`memory-remove`, once at a time:
 a delegate child could otherwise remove its parent's handoff unasked; see
-[Memory](memory.md)); and answering chi's
+[Memory](memory.md)); writing the identity memory, a model note or an overlay
+of either with `memory_write`, `write` or `edit` (`prompt-memory-write`), or a
+model overlay of any memory (`model-overlay-write`), each once at a time and
+only by the user: these change a model's system prompt for later sessions (see
+[Model notes](memory.md#model-notes); a shell command reaches them only under
+`shell-touches-chi`'s text heuristic); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
 pipe, a here-string or a file (`chi-answer-piped`), and `curl`/`wget` to a
 session's `/answer` route (`chi-answer-http`), both once or for the session.

data/docs/internals/prompt-caching.md

@@ -29,7 +29,8 @@ right-hand column happens.
 │   [native thinking token] base prompt                                    │
 │   rg guidance                                                            │  /thinking level,
 │   system identity (+ model overlay)                                      │  /model, editing a
-│   explicit (preloaded) memories                                          │  memory / AGENT.md
+│   model notes (model_notes_* matching the model)                         │  memory / AGENT.md
+│   explicit (preloaded) memories                                          │
 │   AGENT.md                                                               │  (picked up by a new
 │   project + system memory indexes                                        │  process or a rebuild)
 │                         ◄── remote Claude: cache_control breakpoint #1   │

data/docs/memory.md

@@ -25,7 +25,7 @@ Tool behavior:
 Each memory entry may have a companion file named `<name>.<model-key>.md` in the same scope directory. When the entry is read under a matching model, the overlay body is appended automatically, separated by the standard `---` separator with a `Model-specific guidance (<key>):` header.
 
 - **Key derivation**: The harness normalizes the model name sent to the server, without its host prefix (`box:qwen3.6-35b-a3b` keys as `qwen3.6-35b-a3b`; an alias keys as its target, and the alias's own key is read when the target has no overlay) (lowercase, replace non-alphanumeric with `-`, squeeze dashes) to derive the file key. For example, `qwen3.6-35b-a3b` → `qwen3-6-35b-a3b`.
-- **Saving overlays**: Pass `current_model_only: true` to `memory_write` (the harness resolves the model key automatically). This writes the content as `<name>.<model-key>.md` and skips index maintenance.
+- **Saving overlays**: Pass `current_model_only: true` to `memory_write` (the harness resolves the model key automatically). This writes the content as `<name>.<model-key>.md` and skips index maintenance. The guardrails bundle asks before a model writes one (`model-overlay-write`). Habits of a model in general go in a [model note](#model-notes), which can name a family or all small models.
 - **Which key is mine**: the system prompt's `Model:` line names the session's model key, and `chi self` (via `execute`) has a `model key` row; both follow `/model`.
 - **In the system prompt**: the identity memory and the preloaded memories (`--memory`, config `memories:`) get their overlays too, as `memory_read` gives them; after `/model` the rebuilt prompt carries the new model's.
 - **Dormancy**: Overlays are only active under the matching model key; other models see the base entry only.
@@ -36,6 +36,79 @@ Each memory entry may have a companion file named `<name>.<model-key>.md` in the
   - The overlay is read in the scope its base is found in: a project memory with the same name shadows a system-scope bundle's base and overlay.
 
 
+## Model notes
+
+A **model note** is a memory named `model_notes_<name>` whose first line says
+which models it is for. It goes into the system prompt of every session on a
+matching model, so it is where a model's own habits go ("explore briefly, then
+act"), independent of the identity memory:
+
+```markdown
+models: deepseek-*|*deepseek-v4*
+Working habits for this model:
+- Explore briefly, then act.
+```
+
+- **`models:`**: `|`-separated entries, each `small` (a small model per
+  `guardrails.small_models`, see [Guardrails](guardrails.md)) or a glob
+  (case-insensitive, `*`, `?`, `{a,b}`) on the model id sent to the server
+  (no host prefix) or on its model key. Any entry matching loads the note. The
+  grammar is the guardrails rules' `models:`.
+- **Stacked**: every matching note loads, the system scope's first, then the
+  project's, by name within a scope. Notes add habits; none overrides another.
+- **In the prompt**: their own section right after the identity memory,
+  `Model notes (for <model>, scope=…):`, each note under its name, the
+  `models:` line left out. A note's index line is left out of the prompt's
+  memory indexes (its body is already there, or it isn't for this model); the
+  tools still see it.
+- **Overlays**: a note is read like any memory, so its own
+  `model_notes_<name>.<key>.md` overlay is appended.
+- **Muting**: `chi --mute model_notes_<name>` drops one for a session. Muting
+  `identity` no longer drops a model note.
+- **Names**: no dot after `model_notes_` (`memory_write` refuses one: next to a
+  note of the stem's name it would read as a model overlay); a dotted file
+  made by hand is skipped with a warning. No memory name takes a comma
+  (`memory_read` reads a comma list of names).
+- **The `models:` line**: `memory_write` refuses a `model_notes_` memory whose
+  first line isn't one (`models:`, any case, with at least one entry). A file
+  made by hand without one is skipped with a warning (once, in the debug log)
+  naming the file, and keeps its index line in the prompt.
+- **Asked first**: with the guardrails bundle, a model's write of a memory that
+  reaches the system prompt (identity, a model note, or an overlay of either)
+  with `memory_write`, `write` or `edit`, through a symlink or in any case of
+  the name, asks the user, once at a time (`prompt-memory-write`); so does a
+  model overlay of any memory (`model-overlay-write`). Only the user may allow
+  either, not a parent session. The prompt's `Model:` line tells the model that
+  guidance for it goes in a model note.
+- **Exact prefix**: only files named `model_notes_…` as written load; a
+  `MODEL_NOTES_x.md` (which a case-insensitive disk's listing also returns)
+  doesn't.
+- **Size**: they cost every request. A note over 1,500 characters, or all of a
+  model's notes over 3,000, still loads but warns once.
+- **Timing**: a note takes effect at the next prompt build: a session's start,
+  a resume, a web worker waking, `/model`. A note written mid-session doesn't
+  change the running prompt.
+- **Recorded and shown**: each prompt build writes the notes it carried to the
+  session file (`prompt_notes`: name, scope, size in characters and a short
+  digest of the text), so a session says later what it ran with; `/model`
+  switches record the new model's. `/stats` has a
+  `model notes:      model_notes_deepseek (system, 612 chars)` line, `/model`
+  ends its model line with `; notes: …` (after a switch, the new model's), the
+  web's info bar a `notes: deepseek` chip (the full line in its tooltip), and
+  `chi self` a `model notes` row after `model key`: the notes a prompt of the
+  reported model loads now, the session's `--mute` list left out when it runs
+  in one, `none` without any. None of the others shows a line without notes.
+  A resumed session, or a web worker that woke, shows the saved ones until its
+  first turn builds the prompt again.
+- **Judged**: `ruby script/model_notes_report.rb` (a development script, not
+  shipped) groups stored sessions by model and recorded notes and compares the
+  calls to the first edit and commit, commits per 100 steps, bare `&`, the
+  longest run without an edit and the Continues and steers each needed; run a
+  note on and muted for the same kind of task. See
+  [testing.md](testing.md) ("The model notes report").
+- Without a model note the system prompt is what it was.
+
+
 At startup, the agent reads both scope indexes with blank-name memory reads
 and injects them into the system prompt as `Project memories` and
 `System memories`. A memory muted for the session (`chi --mute NAME`) has its
@@ -46,6 +119,40 @@ names of a comma list are read). Its file and index line are untouched.
 These startup index reads are harness-injected context assembly and are not
 rendered as `tool>` activity lines.
 
+### The index's size
+
+Both indexes go into every prompt in full (a model note's line and a muted
+memory's line are left out), so their size is paid on every request. Nothing caps
+or trims them; chi measures them (tokens estimated as characters /
+`context.chars_per_token`) and shows the size:
+
+- `chi self` has a `memory index` row:
+  `system ~2.0k tokens (54 lines), project ~1.4k tokens (35 lines)`, with
+  `, over 2500` inside the parentheses for a scope over
+  `memory.index_warn_tokens`.
+- `/stats` has `memory index:     ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`,
+  and the web's ctx tooltip (info bar and session card) the same line. It is
+  what this session's prompt holds, measured when the prompt was built (after
+  the session's mutes): a memory written during the session changes neither
+  the running prompt nor this figure until the prompt is built again (a
+  resume, a woken worker, `/model`).
+
+`memory.index_warn_tokens` (default `2500`, per scope; `0` turns it off) is
+the size a write may take an index to before the model is told. When a
+`memory_write` (with content, or a description-only one) or a `write`/`edit` on
+a memory file refreshes an index line and takes its scope's index from at or
+under the limit to over it, the tool result ends with one note:
+
+> Note: the project memory index is now ~2510 tokens (over memory.index_warn_tokens 2500) 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.
+
+The note comes once per crossing: a write while the index is already over gets
+none (the tightening it asks for doesn't start a loop), nor does a remove, a
+model overlay or the verbatim `index` write. Sessions sharing a project's folder
+measure on their own, so writes in parallel sessions that race over the limit
+may each get it. Bundle installs and uninstalls and hand edits
+change index lines without a note; `chi self`'s row shows where an index
+stands.
+
 ## Skills
 
 A **skill** is a memory named `skill_<name>` that holds the steps of a