samagotchi 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c41a6466e51c4da290f55cca9398a3221def773f8ee3235102e97322030c882
-  data.tar.gz: 86bc79ce21478e0420e82fc47307fdf9934bee4a2642cda3c8bbf1c26a248c7e
+  metadata.gz: c0f829b7b7835aab33a8b0f8a69609acc2e1989743c5f77664ab54e76cee9ee2
+  data.tar.gz: d0b1ab5cd60519258beb069528aed7f50d7404d5aa8c28ff30a5a1c5b78e3418
 SHA512:
-  metadata.gz: 52bf3393d2a7ff228aba277aa7fea67b4f82619578ba25d28c061e2256c8ef9a36698a250ca928c1916a3ba7a19ffef56fd8eeda7c232d37661fcd1188d63895
-  data.tar.gz: 40d4c0006a4ac0a9d07072f09d691169d7c8d765eed4be45ff2c0ff5acdb04d5dc2ff20e009429abbdd54822d4a91e212f8efbbca75b43f0671382a1fcf16768
+  metadata.gz: 1a0d363fc07a55b7bfbbdb4263ecb630554376e1cbd4bf641e914933046bfb136ecd36f85386bc9a328c63803db9a49a4c57a0a6425849b90c59f223888b68a1
+  data.tar.gz: ae547e2229da947e57095ac6730b5e0549e8e03633beb79ccd47922d836b2a2a00c04be3385000ef230161a74ac88a02621ef84152253d7c5cb017505cfd1853

data/CHANGELOG.md

@@ -8,6 +8,58 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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 +1955,8 @@ 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.41.0...HEAD
+[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

@@ -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. |
@@ -425,7 +428,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 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 +440,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
@@ -861,7 +880,11 @@ 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
+  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 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`).

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,61 @@ 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.
+- 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 +101,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

data/docs/sessions.md

@@ -65,7 +65,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, sampling?}], warning?}`; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only, and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, sampling?}], warning?}`; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
 - The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).

data/lib/samagotchi/bridge/card_store.rb

@@ -152,14 +152,13 @@ module Samagotchi
         when :tool_call_started
           @iteration = event[:iteration]
           @calls = event[:call_index].to_i
-        when :turn_failed
+        # The turns that stay in the conversation (a failed one whose work
+        # stayed too); a failed one rolled back leaves none.
+        when *Events::TURN_END
           @running = false
-          settle_during(after_turn: false)
-        # The turns that stay in the conversation.
-        when *Events::TURN_KEPT
-          @running = false
-          @turns_done += 1
-          settle_during(after_turn: true)
+          kept = Events.kept_turn?(event)
+          @turns_done += 1 if kept
+          settle_during(after_turn: kept)
         when :card then add_card(event)
         when :hook_notice then add_notice(event)
         # What failed to load (guardrails, plugins): before the first turn

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -71,6 +71,29 @@ rules:
     scopes: [once]
     reason: removes a memory (it goes to the bundle trash, which chi bundle trash lists)
 
+  # The identity memory and the model notes (model_notes_<name>,
+  # docs/memory.md), with their overlays, go into the system prompt of every
+  # later session (a note on the models it names), and a model overlay
+  # (memory_write current_model_only: true) is appended to its memory for
+  # this model: a model, maybe steered by text it read, would be writing its
+  # own system prompt. Every such write asks, once at a time, and only the
+  # user may allow it. memory: prompt is memory_write, write or edit of such a
+  # file right in a memories folder, resolved (symlinks, .., and any case of
+  # the name, as a case-insensitive disk reads it); a shell command naming
+  # chi's config dir asks under shell-touches-chi.
+  - id: prompt-memory-write
+    tool: [memory_write, write, edit]
+    memory: prompt
+    verdict: ask
+    scopes: [once]
+    reason: writes a memory that goes into the system prompt of later sessions (identity, a model note, or an overlay of one)
+  - id: model-overlay-write
+    tool: memory_write
+    memory: overlay
+    verdict: ask
+    scopes: [once]
+    reason: writes a model overlay, guidance added to that memory for this model in later sessions
+
   # ── running code from the network ──────────────────────────────────────
   - id: pipe-to-shell
     tool: shell

data/lib/samagotchi/bundles/guardrails/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: guardrails
-version: 0.8.0
+version: 0.9.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory, writing a memory that reaches the system prompt (identity, model notes) or a model overlay; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
 # models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0;
-# a rule's memory: key (memory-remove) needs 0.36.0: an older chi refuses the rule set (unknown key), so every
-# guarded call would be refused
-requires_chi: ">= 0.36.0"
+# a rule's memory: key (memory-remove) needs 0.36.0, and its overlay and prompt values (model-overlay-write,
+# prompt-memory-write) need 0.41.0: an older chi refuses the rule set, so every guarded call would be refused
+requires_chi: ">= 0.41.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.turn_preamble`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `memory.index_warn_tokens`, `thinking.turn_preamble`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.40.0
+version: 0.41.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:78969929094d2c4f3530529cd54c5c37ce6b13b1c3867a318d9ce07e5b77cd73
-  config_modification_protocol.md: sha256:648b19b1b9f7ca35fccdd69fee4c9886cb8cfb3748ae86affef7457c12164399
-  memory_guide.md: sha256:f7049304a333be842b761037bab5c8e31e890b8f4ad12f092b14ee8deb053c51
+  self_map.md: sha256:9d1b2ff7ff5f237c1b1beed2eb8ecc3069570705a2c1763e533dd15829ff309d
+  config_modification_protocol.md: sha256:2d4135ce4fafcd391d1782dc3a54f7cbf10cd35ebe9f004b2d6cb256517a8451
+  memory_guide.md: sha256:15cd3b24eda853cc458371c6c75809a2d4b5352311d075aaa4384926b5221c27
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -47,6 +47,19 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 **Placeholders:**
 - Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.
 
+## Model notes
+
+A model note is a memory named `model_notes_<name>` whose first line says which models it is for: `models: ` then `|`-separated globs on the model id or the model key (the `Model:` line names both), or `small`. It goes into the system prompt of every later session on a matching model, after the identity, so it holds habits of a model (or a family), not of a task.
+
+```markdown
+models: deepseek-*|*deepseek-v4*
+- Explore briefly, then act.
+```
+
+- Write one only when the user asks for guidance for a model; it changes that model's prompt for every later session. The guardrails ask the user first, as they do for a model overlay.
+- No dot in the name (`model_notes_qwen3-6`, not `model_notes_qwen3.6`), and the `models:` line first: `memory_write` refuses either.
+- It takes effect at the next session start, resume or `/model`, not in the running session.
+
 ## Skills
 
 A skill is a memory named `skill_<name>` (`skill_release`, `skill_deploy_staging`) that holds the steps of a repeatable task done with the user. Next time, follow it; when a step turned out different, fix it in the same turn.