From 8b5b9a52e9b9d6f66ae15e6eb06986148e7118d6 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Sat, 18 Apr 2026 20:54:08 -0400 Subject: [PATCH 1/4] docs(kilo-docs): document actual compaction defaults and triggers Replaces the vague 'usableWindow' language with the real formula (context_window - ~20K reserve), documents the /compact slash command and task-header button, adds env-var overrides, and lists the correct default values. --- .../customize/context/context-condensing.md | 202 ++++++++++++------ 1 file changed, 139 insertions(+), 63 deletions(-) diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 3d010446f3..9a293e0096 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -11,7 +11,7 @@ When working on complex tasks, conversations with Kilo Code can grow long and co ## The Problem: Context Window Limits -Every AI model has a maximum context window - a limit on how much text it can process at once. As your conversation grows with code snippets, file contents, and back-and-forth discussions, you may approach this limit. When this happens, you might experience: +Every AI model has a maximum context window — a limit on how much text it can process at once. As your conversation grows with code snippets, file contents, and back-and-forth discussions, you may approach this limit. When this happens, you might experience: - Slower responses as the model processes more tokens - Higher API costs due to increased token usage @@ -22,47 +22,57 @@ Every AI model has a maximum context window - a limit on how much text it can pr ## The Solution: Auto-Compaction -The new platform uses a **Compaction** system to manage context automatically. When your conversation approaches the token limit, compaction kicks in and produces a structured summary that captures: +Kilo Code uses a **Compaction** system to manage context automatically. When your conversation approaches the token limit, compaction kicks in and produces a structured summary that captures: - The overall goal of the session -- Key discoveries made along the way +- Instructions given along the way +- Key discoveries made - What has been accomplished so far -- Files that were modified +- Relevant files and directories This summary replaces the earlier conversation history, freeing up context window space while maintaining continuity in your work. -## How Compaction Works +## How Compaction Triggers -### Automatic Compaction +### It's absolute tokens, not a percentage -Compaction triggers automatically when the conversation reaches the `usableWindow` token threshold. The full conversation history is sent to a dedicated **compaction agent**, which produces a structured summary. This happens in the background without interrupting your workflow. +Compaction is **not** triggered at a fixed percentage of the context window. It fires when the running token count reaches the model's **usable window**: + +``` +usable = model.limit.input - reserved (if the model exposes an input limit) + = model.limit.context - maxOutput (otherwise) + +trigger when: input + output + cache.read + cache.write >= usable +``` + +- `reserved` defaults to `min(20,000, model_max_output_tokens)` — i.e. roughly **20K tokens** of headroom for the next turn, or less for models with a small output cap. +- `maxOutput` is `min(model.limit.output, 32,000)`. +- The same formula runs for every model; the trigger only varies because different models have different window sizes. There is no per-model-family threshold. +- If a custom model has `limit.context = 0` (unset), auto-compaction never triggers. + +In practice this means compaction fires at roughly **~100% of the model's input window minus a 20K safety buffer**. ### Context Pruning -In addition to compaction, the system can **prune** old tool outputs to reclaim context space incrementally. Tool results older than a 40,000-token recency window are replaced with `"[Old tool result content cleared]"`. This is a lighter-weight mechanism that runs alongside full compaction. +Between turns, Kilo also runs a lighter **prune** pass. It walks completed tool outputs outside a 40,000-token recency window and replaces them with `"[Old tool result content cleared]"`. Pruning runs incrementally so large tool outputs don't consume space forever, even before full compaction is needed. ### Manual Compaction -You can also trigger compaction manually: +You can trigger compaction at any time: -- **CLI TUI**: Press `c` to compact the current session -- **Extension Webview**: Send a `CompactRequest` message to trigger compaction +- **Slash command**: type `/compact` in chat (also findable by typing `smol` or `condense`) +- **Task header button**: click the compact icon in the active task header +- **Settings**: toggle auto-compaction in **Settings → Context** -{% callout type="info" %} -There is no `/condense` chat command on the new platform. Use the keybinding or message-based invocation instead. -{% /callout %} +## Defaults -### The Compaction Process +| Setting | Default | Effect | +| --------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- | +| `compaction.auto` | `true` | Automatically compact when the usable window is reached | +| `compaction.prune` | `true` | Clear old tool outputs beyond the 40K recency window | +| `compaction.reserved` | `min(20,000, model_max_output_tokens)` | Token headroom kept free for the next turn — also defines the compaction trigger point | -When compaction is triggered: - -1. **Threshold Check**: The system detects that context usage has reached the `usableWindow` limit -2. **Agent Summarization**: The full conversation history is sent to a dedicated compaction agent -3. **Structured Summary**: The agent produces a summary covering the goal, discoveries, accomplishments, and modified files -4. **Replacement**: The detailed history is replaced with the compacted summary -5. **Continuation**: You continue working with the freed-up context space - -## Configuration Options +## Configuration Compaction is configured in your `kilo.jsonc` file: @@ -70,64 +80,97 @@ Compaction is configured in your `kilo.jsonc` file: { "compaction": { "auto": true, // Enable or disable automatic compaction - "reserved": 4096, // Number of tokens to reserve (keep free) after compaction "prune": true, // Enable pruning of old tool outputs beyond the recency window + "reserved": 20000, // Token buffer kept free; smaller = later trigger, larger = earlier trigger }, } ``` -| Option | Type | Description | -| --------------------- | ------- | ------------------------------------------------------------------------ | -| `compaction.auto` | boolean | Enable or disable automatic compaction when the context threshold is hit | -| `compaction.reserved` | number | Number of tokens to reserve after compaction | -| `compaction.prune` | boolean | Enable pruning of old tool outputs outside the 40K token recency window | +| Option | Type | Default | Description | +| --------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------ | +| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | +| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | +| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn; lower values delay the compaction trigger | + +### Use a different model for compaction + +Summarization can use a cheaper or larger-context model than your main agent. Configure a dedicated compaction agent: + +```jsonc +{ + "agent": { + "compaction": { + "model": "anthropic/claude-haiku-4-5", + }, + }, +} +``` + +If no compaction agent is set, the current session's model is used. + +### Environment overrides + +| Variable | Effect | +| ------------------------------------ | ------------------------------------------------- | +| `KILO_DISABLE_AUTOCOMPACT=1` | Forces `compaction.auto = false` | +| `KILO_DISABLE_PRUNE=1` | Forces `compaction.prune = false` | +| `KILO_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | Overrides the 32,000 default output-token ceiling | {% /tab %} {% tab label="CLI" %} ## The Solution: Auto-Compaction -The new platform uses a **Compaction** system to manage context automatically. When your conversation approaches the token limit, compaction kicks in and produces a structured summary that captures: +Kilo CLI uses a **Compaction** system to manage context automatically. When your conversation approaches the token limit, compaction kicks in and produces a structured summary that captures: - The overall goal of the session -- Key discoveries made along the way +- Instructions given along the way +- Key discoveries made - What has been accomplished so far -- Files that were modified +- Relevant files and directories This summary replaces the earlier conversation history, freeing up context window space while maintaining continuity in your work. -## How Compaction Works +## How Compaction Triggers -### Automatic Compaction +### It's absolute tokens, not a percentage -Compaction triggers automatically when the conversation reaches the `usableWindow` token threshold. The full conversation history is sent to a dedicated **compaction agent**, which produces a structured summary. This happens in the background without interrupting your workflow. +Compaction is **not** triggered at a fixed percentage of the context window. It fires when the running token count reaches the model's **usable window**: + +``` +usable = model.limit.input - reserved (if the model exposes an input limit) + = model.limit.context - maxOutput (otherwise) + +trigger when: input + output + cache.read + cache.write >= usable +``` + +- `reserved` defaults to `min(20,000, model_max_output_tokens)` — i.e. roughly **20K tokens** of headroom for the next turn, or less for models with a small output cap. +- `maxOutput` is `min(model.limit.output, 32,000)`. +- The same formula runs for every model; the trigger only varies because different models have different window sizes. There is no per-model-family threshold. +- If a [custom model](/docs/code-with-ai/agents/custom-models) has `limit.context = 0` (unset), auto-compaction never triggers. + +In practice this means compaction fires at roughly **~100% of the model's input window minus a 20K safety buffer**. ### Context Pruning -In addition to compaction, the system can **prune** old tool outputs to reclaim context space incrementally. Tool results older than a 40,000-token recency window are replaced with `"[Old tool result content cleared]"`. This is a lighter-weight mechanism that runs alongside full compaction. +Between turns, Kilo also runs a lighter **prune** pass. It walks completed tool outputs outside a 40,000-token recency window and replaces them with `"[Old tool result content cleared]"`. Pruning runs incrementally so large tool outputs don't consume space forever, even before full compaction is needed. ### Manual Compaction -You can also trigger compaction manually: +You can trigger compaction at any time: -- **CLI TUI**: Press `c` to compact the current session -- **Extension Webview**: Send a `CompactRequest` message to trigger compaction +- **Slash command**: type `/compact` in the TUI (alias: `/summarize`) +- **Keybinding**: press `c` in the TUI -{% callout type="info" %} -There is no `/condense` chat command on the new platform. Use the keybinding or message-based invocation instead. -{% /callout %} +## Defaults -### The Compaction Process +| Setting | Default | Effect | +| --------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- | +| `compaction.auto` | `true` | Automatically compact when the usable window is reached | +| `compaction.prune` | `true` | Clear old tool outputs beyond the 40K recency window | +| `compaction.reserved` | `min(20,000, model_max_output_tokens)` | Token headroom kept free for the next turn — also defines the compaction trigger point | -When compaction is triggered: - -1. **Threshold Check**: The system detects that context usage has reached the `usableWindow` limit -2. **Agent Summarization**: The full conversation history is sent to a dedicated compaction agent -3. **Structured Summary**: The agent produces a summary covering the goal, discoveries, accomplishments, and modified files -4. **Replacement**: The detailed history is replaced with the compacted summary -5. **Continuation**: You continue working with the freed-up context space - -## Configuration Options +## Configuration Compaction is configured in your `kilo.jsonc` file: @@ -135,17 +178,41 @@ Compaction is configured in your `kilo.jsonc` file: { "compaction": { "auto": true, // Enable or disable automatic compaction - "reserved": 4096, // Number of tokens to reserve (keep free) after compaction "prune": true, // Enable pruning of old tool outputs beyond the recency window + "reserved": 20000, // Token buffer kept free; smaller = later trigger, larger = earlier trigger }, } ``` -| Option | Type | Description | -| --------------------- | ------- | ------------------------------------------------------------------------ | -| `compaction.auto` | boolean | Enable or disable automatic compaction when the context threshold is hit | -| `compaction.reserved` | number | Number of tokens to reserve after compaction | -| `compaction.prune` | boolean | Enable pruning of old tool outputs outside the 40K token recency window | +| Option | Type | Default | Description | +| --------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------ | +| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | +| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | +| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn; lower values delay the compaction trigger | + +### Use a different model for compaction + +Summarization can use a cheaper or larger-context model than your main agent. Configure a dedicated compaction agent: + +```jsonc +{ + "agent": { + "compaction": { + "model": "anthropic/claude-haiku-4-5", + }, + }, +} +``` + +If no compaction agent is set, the current session's model is used. + +### Environment overrides + +| Variable | Effect | +| ------------------------------------ | ------------------------------------------------- | +| `KILO_DISABLE_AUTOCOMPACT=1` | Forces `compaction.auto = false` | +| `KILO_DISABLE_PRUNE=1` | Forces `compaction.prune = false` | +| `KILO_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | Overrides the 32,000 default output-token ceiling | {% /tab %} {% tab label="VSCode (Legacy)" %} @@ -219,17 +286,26 @@ If the condensed summary doesn't capture important details: ## Best Practices -### When to Condense +### When to Compact - **Long sessions**: If you've been working for an extended period on a complex task - **Before major transitions**: When switching to a different aspect of your project -- **When prompted**: When Kilo Code suggests condensing or compaction due to context limits +- **When approaching limits**: Run `/compact` manually before hitting the automatic trigger if you want control over _when_ the summary is produced + +### Tuning `compaction.reserved` + +The `reserved` value is a trade-off: + +- **Lower value** (e.g. `10000`) → compaction triggers later, you get more turns out of the raw window, but you risk a mid-turn context overflow if a single response is larger than the buffer. +- **Higher value** (e.g. `40000`) → compaction triggers earlier, fewer overflow errors, but shorter effective conversations between summaries. + +The default of `~20K` is tuned to leave room for a full-size assistant response plus tool output. ### Maintaining Context Quality - **Be specific in your initial task**: A clear task description helps create better summaries -- **Use AGENTS.md**: Combine with [AGENTS.md](/docs/customize/agents-md) for persistent project context that doesn't need to be condensed -- **Review the summary**: After condensing or compaction, the summary is visible in your chat history +- **Use AGENTS.md**: Combine with [AGENTS.md](/docs/customize/agents-md) for persistent project context that doesn't need to be compacted +- **Review the summary**: After compaction, the summary is visible in your chat history ## Related Features From 2dabf6821fb4fbfe990f3e14f8e59d4fb32ce4d4 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Sat, 18 Apr 2026 20:57:10 -0400 Subject: [PATCH 2/4] docs(kilo-docs): drop defensive framing in compaction trigger section --- .../customize/context/context-condensing.md | 24 ++++++++----------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 9a293e0096..9aa8b8738a 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -34,9 +34,9 @@ This summary replaces the earlier conversation history, freeing up context windo ## How Compaction Triggers -### It's absolute tokens, not a percentage +### Automatic trigger -Compaction is **not** triggered at a fixed percentage of the context window. It fires when the running token count reaches the model's **usable window**: +Compaction fires when the running token count reaches the model's **usable window**: ``` usable = model.limit.input - reserved (if the model exposes an input limit) @@ -45,12 +45,10 @@ usable = model.limit.input - reserved (if the model exposes an input limi trigger when: input + output + cache.read + cache.write >= usable ``` -- `reserved` defaults to `min(20,000, model_max_output_tokens)` — i.e. roughly **20K tokens** of headroom for the next turn, or less for models with a small output cap. +- `reserved` defaults to `min(20,000, model_max_output_tokens)` — typically **20K tokens** of headroom for the next turn, or less for models with a small output cap. - `maxOutput` is `min(model.limit.output, 32,000)`. -- The same formula runs for every model; the trigger only varies because different models have different window sizes. There is no per-model-family threshold. -- If a custom model has `limit.context = 0` (unset), auto-compaction never triggers. - -In practice this means compaction fires at roughly **~100% of the model's input window minus a 20K safety buffer**. +- The same formula applies to every model; the effective threshold varies only because different models have different window sizes. +- If a custom model has `limit.context = 0` (unset), auto-compaction does not run. ### Context Pruning @@ -133,9 +131,9 @@ This summary replaces the earlier conversation history, freeing up context windo ## How Compaction Triggers -### It's absolute tokens, not a percentage +### Automatic trigger -Compaction is **not** triggered at a fixed percentage of the context window. It fires when the running token count reaches the model's **usable window**: +Compaction fires when the running token count reaches the model's **usable window**: ``` usable = model.limit.input - reserved (if the model exposes an input limit) @@ -144,12 +142,10 @@ usable = model.limit.input - reserved (if the model exposes an input limi trigger when: input + output + cache.read + cache.write >= usable ``` -- `reserved` defaults to `min(20,000, model_max_output_tokens)` — i.e. roughly **20K tokens** of headroom for the next turn, or less for models with a small output cap. +- `reserved` defaults to `min(20,000, model_max_output_tokens)` — typically **20K tokens** of headroom for the next turn, or less for models with a small output cap. - `maxOutput` is `min(model.limit.output, 32,000)`. -- The same formula runs for every model; the trigger only varies because different models have different window sizes. There is no per-model-family threshold. -- If a [custom model](/docs/code-with-ai/agents/custom-models) has `limit.context = 0` (unset), auto-compaction never triggers. - -In practice this means compaction fires at roughly **~100% of the model's input window minus a 20K safety buffer**. +- The same formula applies to every model; the effective threshold varies only because different models have different window sizes. +- If a [custom model](/docs/code-with-ai/agents/custom-models) has `limit.context = 0` (unset), auto-compaction does not run. ### Context Pruning From b296b8f797c8684df13d2f218883f14769f78d08 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Sat, 18 Apr 2026 20:59:43 -0400 Subject: [PATCH 3/4] docs(kilo-docs): rewrite trigger rules in prose --- .../customize/context/context-condensing.md | 28 ++++--------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 9aa8b8738a..31e15de5ad 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -36,19 +36,11 @@ This summary replaces the earlier conversation history, freeing up context windo ### Automatic trigger -Compaction fires when the running token count reaches the model's **usable window**: +Kilo tracks the total token count for the session — input, output, and cached reads and writes — and compares it to the model's context window. Compaction runs when the total fills the window minus a reserved buffer of headroom kept free for the next turn. -``` -usable = model.limit.input - reserved (if the model exposes an input limit) - = model.limit.context - maxOutput (otherwise) +The default buffer is 20,000 tokens, or the model's maximum output size if that is smaller. On models that advertise an output cap of up to 32,000 tokens, Kilo uses that cap as the reserve when no input limit is set. The size of the buffer is the same across models; only the overall window size differs, so larger-context models reach the trigger later in absolute token terms. -trigger when: input + output + cache.read + cache.write >= usable -``` - -- `reserved` defaults to `min(20,000, model_max_output_tokens)` — typically **20K tokens** of headroom for the next turn, or less for models with a small output cap. -- `maxOutput` is `min(model.limit.output, 32,000)`. -- The same formula applies to every model; the effective threshold varies only because different models have different window sizes. -- If a custom model has `limit.context = 0` (unset), auto-compaction does not run. +Custom models that do not declare a context window are not tracked, and auto-compaction does not run for them. ### Context Pruning @@ -133,19 +125,11 @@ This summary replaces the earlier conversation history, freeing up context windo ### Automatic trigger -Compaction fires when the running token count reaches the model's **usable window**: +Kilo tracks the total token count for the session — input, output, and cached reads and writes — and compares it to the model's context window. Compaction runs when the total fills the window minus a reserved buffer of headroom kept free for the next turn. -``` -usable = model.limit.input - reserved (if the model exposes an input limit) - = model.limit.context - maxOutput (otherwise) +The default buffer is 20,000 tokens, or the model's maximum output size if that is smaller. On models that advertise an output cap of up to 32,000 tokens, Kilo uses that cap as the reserve when no input limit is set. The size of the buffer is the same across models; only the overall window size differs, so larger-context models reach the trigger later in absolute token terms. -trigger when: input + output + cache.read + cache.write >= usable -``` - -- `reserved` defaults to `min(20,000, model_max_output_tokens)` — typically **20K tokens** of headroom for the next turn, or less for models with a small output cap. -- `maxOutput` is `min(model.limit.output, 32,000)`. -- The same formula applies to every model; the effective threshold varies only because different models have different window sizes. -- If a [custom model](/docs/code-with-ai/agents/custom-models) has `limit.context = 0` (unset), auto-compaction does not run. +[Custom models](/docs/code-with-ai/agents/custom-models) that do not declare a context window are not tracked, and auto-compaction does not run for them. ### Context Pruning From 70b38bc1795827a16b116d8f716df2b08731a011 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Sat, 18 Apr 2026 23:48:18 -0400 Subject: [PATCH 4/4] docs(kilo-docs): clarify reserved buffer behavior per model type compaction.reserved only applies when a model declares a separate input limit. For models with just a single context window, the reserve is derived from the output cap instead. --- .../customize/context/context-condensing.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 31e15de5ad..d9666889c3 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -38,7 +38,7 @@ This summary replaces the earlier conversation history, freeing up context windo Kilo tracks the total token count for the session — input, output, and cached reads and writes — and compares it to the model's context window. Compaction runs when the total fills the window minus a reserved buffer of headroom kept free for the next turn. -The default buffer is 20,000 tokens, or the model's maximum output size if that is smaller. On models that advertise an output cap of up to 32,000 tokens, Kilo uses that cap as the reserve when no input limit is set. The size of the buffer is the same across models; only the overall window size differs, so larger-context models reach the trigger later in absolute token terms. +How the buffer is chosen depends on what the model declares. When the model advertises a separate input limit, the buffer defaults to 20,000 tokens (or the model's maximum output size, whichever is smaller). When the model only declares a single context window, Kilo instead reserves the model's full output cap — up to 32,000 tokens. Custom models that do not declare a context window are not tracked, and auto-compaction does not run for them. @@ -76,11 +76,11 @@ Compaction is configured in your `kilo.jsonc` file: } ``` -| Option | Type | Default | Description | -| --------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------ | -| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | -| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | -| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn; lower values delay the compaction trigger | +| Option | Type | Default | Description | +| --------------------- | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | +| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | +| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn. Applies only to models that advertise a separate input limit; models with a single context window use their full output cap as the reserve instead. | ### Use a different model for compaction @@ -127,7 +127,7 @@ This summary replaces the earlier conversation history, freeing up context windo Kilo tracks the total token count for the session — input, output, and cached reads and writes — and compares it to the model's context window. Compaction runs when the total fills the window minus a reserved buffer of headroom kept free for the next turn. -The default buffer is 20,000 tokens, or the model's maximum output size if that is smaller. On models that advertise an output cap of up to 32,000 tokens, Kilo uses that cap as the reserve when no input limit is set. The size of the buffer is the same across models; only the overall window size differs, so larger-context models reach the trigger later in absolute token terms. +How the buffer is chosen depends on what the model declares. When the model advertises a separate input limit, the buffer defaults to 20,000 tokens (or the model's maximum output size, whichever is smaller). When the model only declares a single context window, Kilo instead reserves the model's full output cap — up to 32,000 tokens. [Custom models](/docs/code-with-ai/agents/custom-models) that do not declare a context window are not tracked, and auto-compaction does not run for them. @@ -164,11 +164,11 @@ Compaction is configured in your `kilo.jsonc` file: } ``` -| Option | Type | Default | Description | -| --------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------ | -| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | -| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | -| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn; lower values delay the compaction trigger | +| Option | Type | Default | Description | +| --------------------- | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `compaction.auto` | boolean | `true` | Enable or disable automatic compaction when the usable window is reached | +| `compaction.prune` | boolean | `true` | Enable pruning of old tool outputs outside the 40K token recency window | +| `compaction.reserved` | number | `min(20000, model_max_output)` | Token headroom reserved for the next turn. Applies only to models that advertise a separate input limit; models with a single context window use their full output cap as the reserve instead. | ### Use a different model for compaction @@ -274,12 +274,12 @@ If the condensed summary doesn't capture important details: ### Tuning `compaction.reserved` -The `reserved` value is a trade-off: +On models that advertise a separate input limit, the `reserved` value is a trade-off: - **Lower value** (e.g. `10000`) → compaction triggers later, you get more turns out of the raw window, but you risk a mid-turn context overflow if a single response is larger than the buffer. - **Higher value** (e.g. `40000`) → compaction triggers earlier, fewer overflow errors, but shorter effective conversations between summaries. -The default of `~20K` is tuned to leave room for a full-size assistant response plus tool output. +The default of `~20K` is tuned to leave room for a full-size assistant response plus tool output. The setting has no effect on models with a single context window, which always reserve their full output cap instead. ### Maintaining Context Quality