samagotchi 0.39.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15442c0fe342d1193ff595b31c554f886076fc4da7dac938fe319ec784e053c6
-  data.tar.gz: 37e73e8590db29ba273346191954ba96b72de468a46663bc2f8820807d95278d
+  metadata.gz: c0f829b7b7835aab33a8b0f8a69609acc2e1989743c5f77664ab54e76cee9ee2
+  data.tar.gz: d0b1ab5cd60519258beb069528aed7f50d7404d5aa8c28ff30a5a1c5b78e3418
 SHA512:
-  metadata.gz: a7d252dbf3ef0eb6ea34aa61bd47e5da389bf17b5f0f4784c9c0e2bf69d22732e83db29b8652bce40ef7ac4a0593e48bc481eb63b9b86a2485ff4027dac1de5f
-  data.tar.gz: 50d569dc04ca76c690c9f4f91ffcec90d85b54445b07f63d2bab1fc6aed5a47d214d9b400faa9b3915783a10e9952613b1a0b0db6361accb514eb4aab7ad3e67
+  metadata.gz: 1a0d363fc07a55b7bfbbdb4263ecb630554376e1cbd4bf641e914933046bfb136ecd36f85386bc9a328c63803db9a49a4c57a0a6425849b90c59f223888b68a1
+  data.tar.gz: ae547e2229da947e57095ac6730b5e0549e8e03633beb79ccd47922d836b2a2a00c04be3385000ef230161a74ac88a02621ef84152253d7c5cb017505cfd1853

data/CHANGELOG.md

@@ -8,6 +8,87 @@ 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
+
+- Experimental: the `forget` layer of `llm_context.strategy` (`[stale, forget]`, per model or host as ever). That
+  model gets a tool, `forget_outputs`, to forget its own tool outputs: each output shows an id (`[#t41]`), and a
+  forget replaces the outputs named with a stub holding the model's note (required; the session keeps the outputs).
+  `keep` keeps lines of an output, `restore` brings a non-read one back; outputs of the last `protect_steps` steps,
+  and reads of files edited in them unless lines are kept, are refused. The stubs reach the prompt under
+  `llm_context.apply`. `llm_context.policy` is the sentence the tool's description carries. Off, the tool list and the
+  prompt are what they were. See [docs/configuration.md](docs/configuration.md) ("LLM context: the forget layer").
+- `llm_context.budget_tokens` (and per model or host `llm_context_budget_tokens`), off by default: a soft context
+  budget the `[CONTEXT: …]` lines count against instead of the window. Under `forget` those lines show
+  `~N/M tokens in use` and offer the tool in tiers (a readout, then "tidy once", then "compact settled outputs now"),
+  at a turn's start, mid-turn only in the top tier.
+- The replay bench's `forget_outputs` strategy asks a model at chi's forget offer and scores its picks, call rate and
+  notes (`--forget-model`, `--out`, `--budget`, `--max-cost`).
+
+### Changed
+
+- Web: session cards no longer show the "mem N" chip, leaving room for the delegate chip; the card's tooltip and the
+  open session's info bar still list the memories used.
+
+### Fixed
+
+- Web: a session card's hover tooltip (id, update time, status, memories) was empty since 0.35.0.
+
+Update with `chi update`: it updates loop-guard (0.3.6: ignores `forget_outputs`).
+
 ## [0.39.0] - 2026-10-07
 
 ### Added
@@ -1874,7 +1955,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.39.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
 [0.37.0]: https://github.com/dm1try/samagotchi/compare/v0.36.0...v0.37.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

@@ -855,6 +855,81 @@ file is read.
 To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
 `config.yml` (env `SAMAGOTCHI_SKIP_AGENT_MD=true`).
 
+## LLM context: the forget layer
+
+Experimental, off by default. With `forget` in a model's `llm_context.strategy` (next to `stale`), chi offers that
+model a tool, `forget_outputs`, to free context by forgetting its own tool outputs. Nothing changes for a model
+without it: no ids, no tool, the same prompt.
+
+```yaml
+llm_context:
+  budget_tokens: 64000        # optional: the [CONTEXT: …] lines count against 64k, not the window
+models:
+  deepseek-v4.1-flash:
+    llm_context_strategy: [stale, forget]
+    llm_context_apply: next_request
+```
+
+- **Ids.** Every tool output the model sees starts with its id after the tool's name, `[read]` then `[#t41] …`.
+  Outputs a session saved before chi gave them ids show none and can't be forgotten.
+- **Forgetting.** `forget_outputs(ids: ["t41", "t42"], note: "…")` replaces each output with a stub holding the note
+  (`[read] [#t41] (forgotten) …`); the call stays, and the session keeps the outputs. The note is required. Outputs
+  one call forgot that follow one another carry the note once: the rest say `(forgotten with t41: see its note)`.
+  `keep: ["t42:12-40"]` forgets t42 except those lines, which follow its stub: a read's lines are the file's line
+  numbers (a read from `start_line` 120 starts at 120), other outputs count from 1.
+- **Refused, per id, with the reason in the result:** an output from the last `llm_context.protect_steps` steps
+  before the forget's own (1: the output the model just got); a read of a file edited or written in them, unless the
+  forget keeps lines of it; a keep outside the output's lines, of a big file's head/tail preview, or holding all of
+  it; an output too small for a stub to free anything; one already stubbed or forgotten; an unknown id, or one whose
+  output chi can't pair with its call for sure (it shows no id). The system prompt, user messages, steers and context
+  notes have no ids.
+- **When stubs reach the prompt** follows `llm_context.apply`, as `stale`'s do: the result says
+  `applied, the next request sends the stubs (frees …)` or `staged until the turn ends`.
+- **Restore.** `forget_outputs(restore: ["t45"])` brings a forgotten output back with the next request, whatever
+  `llm_context.apply` says (the model wants the text now; the result says what the server reads again); a non-read
+  stub says `[restore: t45]`. A read whose stub was sent isn't restored (read the file again: it may have changed); one
+  still staged is.
+- **The description** carries the note contract (facts carried forward, quoted, marked VERIFIED or UNVERIFIED; what
+  was ruled out, with the reason and "do not retry"; the commands tried; a NEXT line), the cost of an edit (the
+  server reads everything after it again: forget in one batch, older outputs first) and `llm_context.policy`.
+- **Offers.** Under `forget` the `[CONTEXT: …]` line becomes a readout, `~52k/64k tokens in use`, and offers the tool
+  in tiers, never "forget now": the readout alone in the lower guided buckets; "finish the unit of work in flight,
+  then tidy once" in the bucket under the top; "compact settled outputs now: keep what you'll still edit against;
+  don't wipe" in the top bucket or over `llm_context.budget_tokens`. They come at a turn's first request (the turn
+  before it answered); mid-turn only the top tier offers. Over the budget the compact offer comes every turn.
+- `/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
@@ -917,13 +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` isn't built yet: a list with it warns and is `none`; an unknown name warns and is `none`. `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` (`none` or `stale` for now). |
-| `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.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`. 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. |
+| `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. 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/hooks.md

@@ -440,6 +440,7 @@ stripped of surrounding whitespace, except file text, an edit's
 | `delegate` | `task` | — | `model`, `session`, `cwd`, `wait`, `timeout` |
 | `delegate_result` | — | — | `session`, `timeout` |
 | `ask_user_question` | `question` | — | `question`, `options`, `header`, `multi_select`, `allow_freeform` |
+| `forget_outputs` | `note` | — | `ids`, `note`, `keep`, `restore` |
 
 A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
 `new_text:` (its `content:` is `""`). A plugin or MCP tool's call has its

data/docs/internals/context-telemetry.md

@@ -31,6 +31,22 @@ Emission behavior:
   `context.status_thresholds` the top bucket reads critical, the one below it
   elevated, the next moderate, and the first bucket (and the rest below) healthy.
 
+Under an LLM context strategy (`ContextStatus.new(llm_context:)`, the turn's `LLMContextStrategy::Resolved`, given by
+both loops):
+
+- `llm_context.budget_tokens` (or a model's or host's `llm_context_budget_tokens`): the buckets count against the
+  budget instead of the window, the smaller of the two. The event's `window_tokens` and the status line's percentage
+  are of it too, and so is `payoff`'s top bucket.
+- The forget layer replaces the guidance with tiered offers of `forget_outputs`, each line a readout,
+  `[CONTEXT: ~52k/64k tokens in use (bucket=60plus). …]`: the readout alone in the guided buckets below the top two
+  (CLM: how-to at low pressure makes a model wipe everything); "Finish the unit of work in flight, then tidy once
+  with forget_outputs: …" in the one under the top; "Compact settled outputs now with forget_outputs: keep what
+  you'll still edit against; don't wipe." in the top bucket, or over the budget (`observe`'s absolute check). They
+  come at a turn's first request (`iteration_index` 0: the turn before answered, its outputs are settled) on a rise,
+  again when the conversation's last line was the readout alone, and every turn while over the budget; mid-turn a
+  rise offers only in the top tier, a lower one gets the readout alone (the layout check: pushed mid-task, models
+  forget at the base rate). See internals/llm-context-forget.md.
+
 Configuration:
 
 - `SAMAGOTCHI_CONTEXT_STATUS` (`true` by default): set to `false` or `0` to disable telemetry.

data/docs/internals/llm-context-bench.md

@@ -54,7 +54,9 @@ The proxies are the context-edit spike's (lexical and lenient: a basename mentio
 
 - `none`: nothing changes. The base.
 - `forget_all`: at the turn's end, forget every output in context with an empty note. The spike's base rate; about
-  what a model told "free context now" does.
+  what a model told "free context now" does. Its stubs, and the picks', go through the view as chi sends forgets: a
+  call's note on the first of its outputs in a row and a pointer to it on the rest, and `[#tN]` ids on every output
+  with a stored id (P4).
 - `stale`: chi's own stale layer (`Samagotchi::LLMContextStale`) as chi runs it: each read a later read covering its
   lines superseded is stubbed from the request after that read (chi applies it at the next request), so a case's
   numbers count every stub since the session began. An edit or write of the file supersedes nothing, nor does a read
@@ -67,13 +69,25 @@ The proxies are the context-edit spike's (lexical and lenient: a basename mentio
   modelled (the bench has no window), so `payoff` applies at a request only when the freed tokens are at least the
   tail. A turn-end batch's re-prefill is counted at the next turn's first request even where chi's warm-up would
   prefill it while the user reads.
-- `forget_outputs` (P4): a slot. It prints "not built yet" until its phase adds it to
-  `LLMContextBench::Strategies`; a strategy answers `#plans(kase)` with `Plan`s of `PlannedEdit`s (the output id, the
-  edit kind, the note, the request it first reaches), and the scorer and the report take it as is.
+- `forget_outputs` (P4): chi's forget layer as chi offers it, at each case: the next turn's first request, after a
+  turn the model answered. The request is what chi sends there under `[stale, forget]`, built by chi's own code: the
+  conversation up to and with the next user message (outputs of a legacy entry get ids as chi gives new ones),
+  stale's stubs, every output led by its `[#tN]` id (`LLMContextView`), the `[CONTEXT: …]` line chi's `ContextStatus`
+  adds at a turn's start under `--budget N` (default 64000; no line below its guided buckets, so a small case may get
+  none), and the chat messages and tools of chi's `ChatLoop`, `forget_outputs` with its real description. The model
+  (`--forget-model MODEL`, a chi model ref on an `api: openai` host) answers once; a `forget_outputs` call among its
+  calls runs through chi's `LLMContextForget` (refusals, `protect_steps`, `keep`), and the row scores stale's stubs
+  plus the forgets. Each answer is saved in `--out DIR` (`<case>.forget_offer.json`) and read back, so a rerun asks
+  only for the rest (an error isn't saved); `--out` alone scores saved answers; `--max-cost USD` stops the asking
+  once the costs the server reports reach it (exit 1, the answers so far kept). The row's notes give the call rate
+  (`called`, `no_call`, `error`, `unasked`), the ids chi refused and the notes' mean length. Ids in this row cost
+  tokens too: its freed column is net of them.
 - `--picks LABEL=DIR`: model picks recorded as responses, one file per pick, `<case>.<variant>.json` (the spike's
   `out/<model>/` files, or what `--live` saves). The variant is the row's policy, the label its model.
 
 ```sh
+ruby script/llm_context_bench.rb "$SESSIONS" --strategy none,stale,forget_outputs --forget-model splash:MODEL \
+  --out answers/splash --budget 48000 --cases cases.txt --per-case
 ruby script/llm_context_bench.rb "$SESSIONS" --strategy none,forget_all,stale --per-case
 ruby script/llm_context_bench.rb "$SESSIONS" --strategy none,stale,stale_edits_turn_end,stale_edits_payoff --ends any
 ruby script/llm_context_bench.rb "$SESSIONS" --picks deepseek=picks/deepseek --picks splash=picks/splash --json

data/docs/internals/llm-context-forget.md

@@ -0,0 +1,45 @@
+# The forget layer: forget_outputs
+
+`llm_context.strategy` with `forget` (experimental; user docs: configuration.md, "LLM context: the forget layer")
+lets the model forget its own tool outputs. The pieces:
+
+- **The tool list is per turn.** `Tools::Registry` entries may name an LLM context layer (`layer: :forget`);
+  `#entries/#names/#schemas(layers:)` and `#offered(name, layers:)` leave a gated tool out unless the turn runs under
+  its layer. The turn's layers are `LLMContextStrategy::Resolved#active_layers` (`[]` under none): the native system
+  prompt declares them (`SystemPrompt#build(layers:)`, `Engine#system_prompt` resolving the target's strategy), the
+  chat loop sends them (`ChatLoop#tool_definitions`), the kernel dispatches and lists them (`KernelLoop#dispatch`).
+  Under none and `[stale]` the tool list, the system prompt and the wire requests are what they were. A model switch
+  that changes the layers changes the tool list; it breaks the prompt cache anyway.
+- **Ids** (`LLMContextView`, plan D2): with `:forget` among the view's layers every output with a stored id
+  (`ToolIds`, `tool_ids` on the entry) is sent as `[name]` lead, then `[#tN] `, then its text; derived ids of legacy
+  entries are never shown or forgettable.
+- **The schema** is `ToolDeclarations.forget_outputs_schema(policy:)` (not in `TOOL_SCHEMAS`, which every turn
+  declares; `BUILTIN_SCHEMAS` adds it for `BuiltinCalls`). Its description (about 330 tokens by chars/4, 515 with the
+  parameters) carries the spike's refined text, `llm_context.policy` (read when the Engine builds its registry), the
+  note contract and the cost lesson. Parameters: `ids`, `note`, `keep` (`"t42:12-40"`: forget t42 except
+  those lines; a read's are file lines, kept with the edit's `keep_offset`, start_line - 1), `restore`, none required
+  (a restore needs no note); `Tools::ForgetOutputs.parse` reads ids and ranges from lists, JSON strings or words.
+- **The call** (`KernelLoop#forget_outputs`, through the handler's kctx as ask_user_question does) runs
+  `LLMContextForget.call` on the running turn (`KernelLoop#llm_context_turn`, a `LLMContextForget::Turn` of the
+  turn's conversation and ContextStatus that both loops set as a turn starts). It names only outputs that pair with
+  their calls for sure (`LLMContextStale.paired_runs`: by tool_call_id, or a joined entry's runs by their calls'
+  `[name]` leads); the view shows ids only on those. The conversation's last step is the forget's own (both loops
+  add the model's entry before its calls run). Per id it refuses (with the reason in the result): an output of the
+  `protect_steps` steps before that one; a read `LLMContextStale.protected_ids` names (a file edited or written in
+  those steps, counted with the forget's own: `protect_steps + 1`) unless the forget keeps lines of it; a keep
+  outside the output's lines, of a preview, or holding all of it; an output of `SMALL` (80) chars or less; an output
+  with an edit already; an unknown id. What passes is saved as a staged `LLMContextEdit` of kind `:forget` (`by:
+  "model"`, the note, `keep`), and the apply rule runs at once as at a request (`KernelLoop#apply_llm_context!`), so
+  the result can say whether the batch goes with the next request or waits for the turn's end. `LLMContextApply`'s
+  protect_steps hold covers stale's stubs only: a forget was checked when it was made.
+- **Restore** takes the forget off the entry (`LLMContextEdit.remove`, a new edits Hash); the next request sends the
+  output again, outside the apply rule (the result says the tail the server reads again, and `ContextStatus#edited!`
+  restarts the estimate). A read whose stub was sent isn't restored; a staged one is.
+- **Stubs** (`LLMContextView`): `(forgotten) <note>` on the first output of a call's forgets in a row, `(forgotten
+  with tN: see its note)` on the rest (a run of the same note, author and stamp, no other output between them),
+  ` [restore: tN]` on a non-read with a stored id, then each kept range under `lines A-B kept:`. The entry keeps its
+  role, tool_call_id and images bookkeeping as for stale.
+- **Offers**: `ContextStatus` (internals/context-telemetry.md).
+- **Persistence**: the edits ride on the entries (plan D3), so `--resume`, rollbacks and forks keep the stubs and the
+  restores; `/stats` counts each applied batch's re-prefill.
+- **Measuring**: the bench's `forget_outputs` strategy (internals/llm-context-bench.md).

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   │