pi-context-kit 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,106 +1,548 @@
1
1
  # pi-context-kit
2
2
 
3
- Context maintenance for [Pi](https://github.com/earendil-works/pi). It uses the active session model for handoff notes; if that request fails or cannot fit, Pi's summary remains the fallback. Offline integration tests use Pi's faux provider.
3
+ pi-context-kit keeps long [Pi](https://github.com/earendil-works/pi) sessions small, so the AI model can continue to work.
4
+ Install it once. The defaults work without configuration.
5
+ Summaries can lose details. `recall` retrieves earlier text on the current branch, but returns only MIME types for images.
6
+
7
+ ## The problem
8
+
9
+ An AI model can read only a limited amount of text at one time. This limit is the **context window**.
10
+ Text is measured in **tokens**. One token is approximately 3 to 4 characters of English text.
11
+
12
+ In a long session, the conversation fills the context window. File reads and command outputs are usually the largest parts.
13
+ When the window is almost full, Pi does a **compaction**: it replaces the old conversation with a summary.
14
+ A summary can lose details, and it costs time and money.
15
+
16
+ pi-context-kit does three things:
17
+
18
+ 1. It replaces repeated file reads and old tool outputs in the model's context.
19
+ 2. When a summary is necessary, it can prepare a handoff note in advance.
20
+ 3. It leaves the original session entries unchanged. The model can retrieve earlier text on the current branch with `recall`.
21
+
22
+ ## Words used in this document
23
+
24
+ | Word | Meaning |
25
+ | --- | --- |
26
+ | Token | A small piece of text. The model counts its memory in tokens. |
27
+ | Context window | The maximum number of tokens that the model can read at one time. |
28
+ | Context | All the text that Pi sends to the model now: instructions, messages, and tool outputs. |
29
+ | Turn | One cycle: the model replies, uses its tools, and stops. |
30
+ | Tool output | The result of a tool, for example the content of a file or the output of a command. |
31
+ | Threshold | The number of tokens at which maintenance starts. |
32
+ | Compaction | Pi replaces the old conversation with a summary. The newest messages stay. |
33
+ | Handoff note | A summary that pi-context-kit writes with the same model as your session. |
34
+ | Pi's summary | The summary that Pi writes when no handoff note is available. |
4
35
 
5
36
  ## Install
6
37
 
7
- ```sh
8
- pi install npm:pi-context-kit
38
+ 1. Open a terminal.
39
+ 2. Type this command and press Enter:
40
+
41
+ ```sh
42
+ pi install npm:pi-context-kit
43
+ ```
44
+
45
+ 3. Restart Pi.
46
+
47
+ To check the installation, type `pi list`. The list must show `npm:pi-context-kit`.
48
+
49
+ To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
50
+
51
+ ## Recommended setup
52
+
53
+ The default setup works without changes. By default, maintenance starts at the same time as Pi's compaction.
54
+ For large context windows, start maintenance earlier. This example starts at 150,000 tokens:
55
+
56
+ 1. Open the file `~/.pi/agent/settings.json` in a text editor. `~` is your home folder.
57
+ 2. Add the `contextKit` block inside the outer `{ }`. Put a comma between this block and the other settings.
58
+
59
+ ```json
60
+ {
61
+ "contextKit": {
62
+ "thresholdTokens": 150000
63
+ }
64
+ }
65
+ ```
66
+
67
+ 3. Save the file.
68
+ 4. In Pi, type `/reload`, or restart Pi.
69
+
70
+ If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: invalid settings`. The incorrect value is ignored and its default is used.
71
+
72
+ To use a setting only in one project, put the same block in the file `.pi/settings.json` in that project folder. Project settings replace global settings.
73
+
74
+ ## What happens during a session
75
+
76
+ ```text
77
+ Every turn ends
78
+ |
79
+ v
80
+ 1. Remove old file reads that a newer read replaced
81
+ |
82
+ v
83
+ Context near the threshold? --yes--> 2. Start a handoff note in the background
84
+ |
85
+ v
86
+ Context above the threshold? --no--> continue to work
87
+ |
88
+ yes
89
+ v
90
+ 3. Prune old tool outputs
91
+ |
92
+ v
93
+ Small enough now? --yes--> continue to work
94
+ |
95
+ no
96
+ v
97
+ 4. Try each method in "methodOrder": handoff, shake, soft
9
98
  ```
10
99
 
11
- ## What it does
100
+ ### 1. Old file reads are replaced
12
101
 
13
- | When | Action |
14
- | --- | --- |
15
- | End of each turn | Replaces older reads only when a newer successful read covers them. Truncated whole-file reads do not cover older ranges. Replacements are limited by `staleSuffixTokens`; this is not a guarantee about provider prompt caching. |
16
- | End of a turn above the threshold | Prunes old tool outputs. It keeps the edits only if they bring the context to 80% of the threshold or less. Otherwise the methods in `methodOrder` run. |
17
- | Before the threshold | Can write a handoff note in the background from the live context. Its lead is one eighth of the threshold, capped at 32,000 tokens. |
18
- | Compaction | Uses a ready background note without waiting. Otherwise it may write a fresh note when the retained context can fit the target. Failed, truncated, oversized, or unavailable notes fall back to Pi's summary. |
19
- | Any time | `recall` searches or reads raw entries on the current branch, including compacted and context-edited messages. Images are represented by MIME metadata, not recovered image pixels. Regex searches run in a worker with a deadline. |
102
+ Sometimes the model reads the same file two times. The first copy is then old.
103
+ pi-context-kit replaces the old copy with this text: `[Superseded by a newer read of this file]`.
104
+
105
+ It does this only when the newer read covers all of the old read. If the newer read was cut short, the old copy stays.
106
+ It does this only when the context is above the threshold, in the same change as pruning, shaking or compaction. Each change to old text makes the provider read all later text again without its cache. With Anthropic, it also removes the model's earlier reasoning from the request. One change near the threshold costs less than one change at each turn.
107
+
108
+ ### 2. A handoff note is prepared in advance
20
109
 
21
- Automatic maintenance runs between model requests:
110
+ Before the context reaches the threshold, the session model writes a handoff note in the background. Your work does not stop.
111
+ The note starts one eighth of the threshold early, with a maximum of 32,000 tokens. With a threshold of 150,000 tokens, it starts at approximately 131,250 tokens.
22
112
 
23
- - At Pi's threshold, Pi compacts between two model requests and the run continues.
24
- - At an earlier `thresholdTokens` or `thresholdPercent`, a handoff is appended only when the retained context and note fit the progress target. Otherwise maintenance continues in the configured order. The extension never calls `ctx.compact()`, which aborts the run.
25
- - The kept part always holds the latest messages and tool results.
26
- - An early automatic handoff can defer while a relevant background note is still being written. Native, manual, and overflow compaction never wait for an unfinished note.
113
+ The note uses the same sections as Pi's summary. It also lists the files that were read and changed.
27
114
 
28
- Notes:
115
+ ### 3. Old tool outputs are pruned
29
116
 
30
- - The handoff note uses the same sections as Pi's summary. It also gets Pi's `<read-files>` and `<modified-files>` sections, which cover the whole branch.
31
- - `/compact <focus>` requests a fresh note for that focus when the retained context leaves enough room. Otherwise Pi handles the request.
32
- - After a context overflow, a ready background note is used. Otherwise Pi's summary runs, because the live context no longer fits the model.
33
- - User-role messages are never shaken, preserving instructions and images. Tool calls and thinking blocks are never edited; each tool call keeps its result, and signed reasoning stays valid. Images removed from eligible tool outputs can only be recalled as metadata.
34
- - With Pi's compaction disabled, only superseded reads are replaced.
35
- - The note request uses the session's thinking level and tool choice, because Anthropic drops the cached messages when either differs. A reply that calls a tool is rejected. The request caps output to the available budget. Providers can differ; failures use Pi's summary. Prompt-cache reuse is provider-dependent and is not guaranteed.
36
- - Subagents run the extension in their own sessions with their own settings. Without a UI, warnings are not shown.
117
+ Above the threshold, old tool outputs are replaced with a short notice, for example:
118
+ `[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]`
119
+
120
+ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this change only if the context becomes small enough. "Small enough" means 80% of the threshold or less.
121
+
122
+ ### 4. Other methods, in order
123
+
124
+ If pruning is not sufficient, pi-context-kit tries the methods in `methodOrder`, one after the other:
125
+
126
+ | Method | What it does | Uses the model? |
127
+ | --- | --- | --- |
128
+ | `handoff` | Replaces the old conversation with the handoff note. The newest messages stay. | Yes |
129
+ | `shake` | Replaces large old code blocks, XML blocks, and images with a short notice. Your messages are never shaken. | No |
130
+ | `soft` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops here. | Yes |
131
+
132
+ Your work continues during these steps. pi-context-kit never stops a running task to compact.
133
+
134
+ ### The `recall` tool
135
+
136
+ The `recall` tool reads original session text, not the shortened context sent to the model. It can:
137
+
138
+ - search earlier conversation text on the current branch, including removed and summarized messages;
139
+ - read an entry's text by ID, with pagination for large entries.
140
+
141
+ Other branches and sessions are excluded. System prompt entries are not searched.
142
+ Images remain in the original session entries, but `recall` returns only their MIME types, not image content.
143
+ The model must call `recall` to retrieve a missing detail. Retrieval is not automatic.
144
+
145
+ ## What maintenance preserves
146
+
147
+ File-read replacement, pruning, and shaking do not rewrite the original session entries.
148
+ In the model's context, these steps preserve:
149
+
150
+ - Your messages, including your instructions and images.
151
+ - The model's tool calls and reasoning. Anthropic can still drop the reasoning after an edited message (see [Old file reads are replaced](#1-old-file-reads-are-replaced)).
152
+ - Tool-call and tool-result pairs. Each tool call keeps its result, but the result content can be shortened.
153
+
154
+ Compaction is different: it replaces older context with a summary, including older user messages. The original entries remain in session history.
37
155
 
38
156
  ## Settings
39
157
 
40
- Add a `contextKit` object to `~/.pi/agent/settings.json` or `.pi/settings.json`. Project settings override global settings. Changes apply after `/reload` or a restart. An invalid value shows a warning and keeps its default. The names follow the `compaction.*` settings of oh-my-pi.
158
+ This section lists every setting. Each setting has its allowed values, its default, and an example.
159
+
160
+ ### Where to put the settings
161
+
162
+ Put all settings in a `contextKit` block, in one of these files:
163
+
164
+ | File | Applies to |
165
+ | --- | --- |
166
+ | `~/.pi/agent/settings.json` | All your projects. `~` is your home folder. |
167
+ | `.pi/settings.json` in a project folder | Only this project. These values replace the values of the global file. |
168
+
169
+ You do not need to set all settings. A missing setting uses its default.
170
+ After a change, type `/reload` in Pi, or restart Pi.
171
+
172
+ ### All settings with their defaults
173
+
174
+ This block sets every setting to its default. It has the same effect as no `contextKit` block.
175
+ Copy only the lines that you want to change.
41
176
 
42
177
  ```json
43
178
  {
44
179
  "contextKit": {
45
- "thresholdTokens": 150000,
46
- "methodOrder": ["handoff", "shake", "soft"]
180
+ "enabled": true,
181
+ "thresholdTokens": -1,
182
+ "thresholdPercent": -1,
183
+ "methodOrder": ["handoff", "shake", "soft"],
184
+ "asyncEnabled": true,
185
+ "supersedeReads": true,
186
+ "progressRatio": 0.8,
187
+ "prune": {
188
+ "enabled": true,
189
+ "protectTokens": 40000,
190
+ "minSavings": 20000,
191
+ "minTokens": 50
192
+ },
193
+ "shake": {
194
+ "protectTokens": 16000,
195
+ "minSavings": 4000,
196
+ "blockMinTokens": 400
197
+ }
47
198
  }
48
199
  }
49
200
  ```
50
201
 
51
- | Setting | Default | Description |
202
+ ### Summary table
203
+
204
+ | Setting | Allowed values | Default | Short description |
205
+ | --- | --- | --- | --- |
206
+ | [`enabled`](#enabled) | `true`, `false` | `true` | Turns all maintenance on or off. |
207
+ | [`thresholdTokens`](#thresholdtokens) | `-1`, or a whole number above 0 | `-1` | Starts maintenance at this number of tokens. |
208
+ | [`thresholdPercent`](#thresholdpercent) | `-1`, or a number above 0, up to 100 | `-1` | Starts maintenance at this percentage of the context window. |
209
+ | [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. |
210
+ | [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. |
211
+ | [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. |
212
+ | [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. |
213
+ | [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. |
214
+ | [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. |
215
+ | [`prune.minSavings`](#pruneminsavings) | A whole number, 0 or more | `20000` | The minimum gain for pruning. |
216
+ | [`prune.minTokens`](#prunemintokens) | A whole number, 0 or more | `50` | Tool outputs smaller than this are never pruned. |
217
+ | [`shake.protectTokens`](#shakeprotecttokens) | A whole number, 0 or more | `16000` | The newest context that is never shaken. |
218
+ | [`shake.minSavings`](#shakeminsavings) | A whole number, 0 or more | `4000` | The minimum gain for shaking. |
219
+ | [`shake.blockMinTokens`](#shakeblockmintokens) | A whole number, 0 or more | `400` | Blocks smaller than this are never shaken. |
220
+
221
+ "Whole number" means a number without decimals, for example `150000`. Do not put spaces, dots, or commas in numbers: write `150000`, not `150,000`.
222
+
223
+ ### When a setting is incorrect
224
+
225
+ pi-context-kit checks each value. If a value is incorrect, Pi shows a warning, and the setting uses its default. The other settings still apply.
226
+
227
+ Example: with `"thresholdTokens": "150000"` (a text in quotes, not a number), Pi shows:
228
+
229
+ ```text
230
+ pi-context-kit: invalid settings, defaults used (contextKit.thresholdTokens must be -1 or a positive integer).
231
+ ```
232
+
233
+ A setting name with a spelling mistake also shows a warning, for example `contextKit.treshold is not a setting`.
234
+
235
+ ### `enabled`
236
+
237
+ Turns all maintenance on or off.
238
+
239
+ - `true` (default): pi-context-kit works as described in this document.
240
+ - `false`: pi-context-kit does nothing. Pi uses only its own summary. The `recall` tool stays available.
241
+
242
+ ```json
243
+ { "contextKit": { "enabled": false } }
244
+ ```
245
+
246
+ ### `thresholdTokens`
247
+
248
+ Maintenance starts when the context is larger than this number of tokens.
249
+
250
+ - `-1` (default): use `thresholdPercent`. If `thresholdPercent` is also `-1`, use Pi's limit.
251
+ - A whole number above 0: start at this number of tokens.
252
+
253
+ This setting has priority over `thresholdPercent`.
254
+ pi-context-kit can start before Pi's limit, never after. If your value is larger than Pi's limit, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply).
255
+
256
+ Example: start at 150,000 tokens.
257
+
258
+ ```json
259
+ { "contextKit": { "thresholdTokens": 150000 } }
260
+ ```
261
+
262
+ | Model context window | Pi's limit (default reserve) | Threshold used |
52
263
  | --- | --- | --- |
53
- | `enabled` | `true` | Set to `false` to disable maintenance and handoff compaction. `recall` stays available. |
54
- | `thresholdTokens` | `-1` | Starts automatic maintenance above this token count. Overrides `thresholdPercent`. `-1` uses `thresholdPercent`. |
55
- | `thresholdPercent` | `-1` | Starts automatic maintenance above this percentage of the context window, at most 99%. `-1` uses Pi's threshold only. |
56
- | `methodOrder` | `["handoff", "shake", "soft"]` | What runs, in order, when pruning is not enough. `handoff`: a note by the session model. `shake`: elides large old code or XML blocks and images, without a model call. `soft`: Pi's summary, written at this threshold when it is below Pi's own. `remote` and `snapcompact` are accepted and skipped, because Pi lacks them. |
57
- | `asyncEnabled` | `true` | Writes the handoff note in the background before the threshold. |
58
- | `supersedeReads` | `true` | Replaces older reads of a file that was read again. |
59
- | `staleSuffixTokens` | `8000` | Replaces superseded reads only when the entire replaced entry and newer suffix fit this many tokens. |
60
- | `progressRatio` | `0.8` | Pruning, shaking, and handoff notes must reduce the estimated context to this fraction of the threshold. |
61
- | `prune.enabled` | `true` | Prunes old tool outputs above the threshold. |
62
- | `prune.protectTokens` | `40000` | Newest tool-output tokens that are never pruned. |
63
- | `prune.minSavings` | `20000` | Prunes nothing unless the savings reach this many tokens. |
64
- | `prune.minTokens` | `50` | Outputs smaller than this are never pruned. |
65
- | `shake.protectTokens` | `16000` | Newest context tokens that are never shaken; user-role messages are always protected. |
66
- | `shake.minSavings` | `4000` | Shakes nothing unless the savings reach this many tokens. |
67
- | `shake.blockMinTokens` | `400` | Blocks smaller than this stay. |
68
-
69
- `methodOrder` controls end-of-turn maintenance. `soft` ends that sequence: below Pi's threshold it compacts with Pi's summary, which updates any previous summary; methods after `soft` do not run. A failed or unavailable handoff can fall back to `shake` before `soft`.
70
-
71
- Pi's compaction hook cannot append context edits. Manual compaction, overflow recovery, and compaction triggered before a turn can use a handoff note or Pi's summary, but cannot run `shake` there.
72
-
73
- Pi still compacts at its own threshold (`compaction.reserveTokens`, `compaction.modelOverrides`). Earlier thresholds request maintenance, not guaranteed compaction: an oversized retained tool result may leave no room for a useful note or summary, and a failed summary is not retried until the next compaction. Budget checks use Pi's token estimates; actual provider token counts and cache behavior can differ.
264
+ | 1,000,000 | 983,616 | 150,000 |
265
+ | 200,000 | 183,616 | 150,000 |
266
+ | 128,000 | 111,616 | 111,616 (Pi's limit is smaller) |
74
267
 
75
- ## Development
268
+ ### `thresholdPercent`
76
269
 
77
- ```sh
78
- npm install
79
- npm run check
270
+ Maintenance starts when the context is larger than this percentage of the model's context window.
271
+
272
+ - `-1` (default): no percentage. If `thresholdTokens` is also `-1`, use Pi's limit.
273
+ - A number above 0, up to 100: start at this percentage. Decimals are allowed, for example `72.5`. Values above 99 are used as 99.
274
+
275
+ pi-context-kit ignores this setting when `thresholdTokens` is not `-1`.
276
+
277
+ Example: start at 75% of the context window.
278
+
279
+ ```json
280
+ { "contextKit": { "thresholdPercent": 75 } }
80
281
  ```
81
282
 
82
- The tests run offline with Pi's faux provider.
283
+ | Model context window | Threshold used |
284
+ | --- | --- |
285
+ | 1,000,000 | 750,000 |
286
+ | 200,000 | 150,000 |
287
+ | 128,000 | 96,000 |
83
288
 
84
- ## Contributing and releases
289
+ Use `thresholdPercent` if you use models with different context windows and you want the same proportion for all of them. Use `thresholdTokens` if you want the same number for all of them.
290
+
291
+ ### `methodOrder`
292
+
293
+ The methods that pi-context-kit tries when pruning is not sufficient, in this order.
294
+
295
+ Allowed values in the list:
296
+
297
+ | Value | What it does | Calls the model? |
298
+ | --- | --- | --- |
299
+ | `"handoff"` | Replaces the old conversation with a handoff note. The newest messages stay. | Yes, the session model |
300
+ | `"shake"` | Replaces large old code blocks, XML blocks, and images with a short notice. | No |
301
+ | `"soft"` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops the list. | Yes, the session model |
302
+ | `"remote"`, `"snapcompact"` | Accepted for oh-my-pi compatibility, but skipped. Pi does not have these methods. | No |
303
+
304
+ Rules:
305
+
306
+ - The order is important. pi-context-kit tries the first method, then the next one.
307
+ - `"soft"` ends the list. Methods after `"soft"` never run.
308
+ - If `"handoff"` is not in the list before `"soft"`, pi-context-kit writes no handoff note at all. This also applies to `/compact` and to background notes. Pi writes its own summary.
309
+ - If `"shake"` is not in the list before `"soft"`, nothing is shaken.
310
+ - A value that appears two times is used one time.
311
+ - An empty list `[]` is allowed. Then pi-context-kit only replaces old file reads and prunes old tool outputs.
312
+
313
+ Common choices:
314
+
315
+ | `methodOrder` | What happens above the threshold |
316
+ | --- | --- |
317
+ | `["handoff", "shake", "soft"]` (default) | Prune. Then a handoff note. If the note fails, shake. Then Pi's summary. |
318
+ | `["shake", "handoff", "soft"]` | Prune and shake together. If that is not sufficient, a handoff note. Then Pi's summary. |
319
+ | `["handoff", "soft"]` | Prune. Then a handoff note. Never shake. |
320
+ | `["shake", "soft"]` | Prune and shake. Then Pi's summary. No handoff note. |
321
+ | `["soft"]` | Prune. Then Pi's summary. |
322
+ | `[]` | Prune only. Pi writes its summary when the context reaches Pi's limit. |
323
+
324
+ Example: try shaking first, because it does not call the model.
325
+
326
+ ```json
327
+ { "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }
328
+ ```
329
+
330
+ ### `asyncEnabled`
331
+
332
+ Prepares the handoff note in the background, before the threshold.
333
+
334
+ - `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. At the threshold, the note is often ready, so compaction is fast.
335
+ - `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
336
+
337
+ This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`.
338
+
339
+ Example: no background requests.
85
340
 
86
- See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and pull requests. Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
341
+ ```json
342
+ { "contextKit": { "asyncEnabled": false } }
343
+ ```
344
+
345
+ ### `supersedeReads`
346
+
347
+ Replaces the old copy of a file when the model reads the same file again.
348
+
349
+ - `true` (default): the old copy becomes `[Superseded by a newer read of this file]`.
350
+ - `false`: all copies stay.
351
+
352
+ This works only above the threshold, together with pruning and shaking.
353
+
354
+ ```json
355
+ { "contextKit": { "supersedeReads": false } }
356
+ ```
357
+
358
+ ### `progressRatio`
359
+
360
+ How small the context must become after a method, as a fraction of the threshold.
361
+ If a method cannot make the context this small, pi-context-kit does not use its result and tries the next method.
362
+
363
+ - `0.8` (default): the context must become 80% of the threshold or less. With a threshold of 150,000 tokens, this is 120,000 tokens.
364
+ - A smaller value, for example `0.6`, gives more free space after maintenance. But each method must remove more, so it fails more often.
365
+ - A larger value, for example `0.95`, makes each method succeed more easily. But maintenance can start again soon after.
366
+
367
+ The value must be above 0 and not more than 1.
368
+
369
+ ```json
370
+ { "contextKit": { "progressRatio": 0.7 } }
371
+ ```
372
+
373
+ ### `prune.enabled`
374
+
375
+ Turns pruning on or off. Pruning replaces old tool outputs with a notice, for example `[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]`.
376
+
377
+ - `true` (default).
378
+ - `false`: tool outputs are never pruned.
379
+
380
+ ```json
381
+ { "contextKit": { "prune": { "enabled": false } } }
382
+ ```
383
+
384
+ ### `prune.protectTokens`
385
+
386
+ The newest tool outputs, up to this number of tokens, are never pruned. Thus the model keeps its most recent results.
387
+
388
+ - `40000` (default).
389
+ - A larger value keeps more recent outputs, but removes less.
87
390
 
88
- 1. Open a pull request. CI runs `npm run check` on Node 22 and 24.
89
- 2. Add user-visible changes under `## Unreleased` in `CHANGELOG.md`.
90
- 3. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes.
91
- 4. Run `npm run release -- <patch|minor|major|x.y.z>` from an up-to-date, clean `main`. This opens a release PR with matching package and lockfile versions, versioned notes, and an empty `Unreleased` section.
92
- 5. Merge the release PR, then wait for CI to succeed on the exact `main` commit you want to publish.
93
- 6. Create `vX.Y.Z` at that commit and push that tag. The tag must match the package version. Release tags cannot be moved or deleted.
94
- 7. As the repository owner, launch **Publish release** at that tag: `gh workflow run release.yml --ref vX.Y.Z -f tag=vX.Y.Z`.
95
- 8. Approve the `npm` environment deployment. The owner can approve their own run; no third-party approval is needed.
391
+ ```json
392
+ { "contextKit": { "prune": { "protectTokens": 60000 } } }
393
+ ```
394
+
395
+ ### `prune.minSavings`
396
+
397
+ Pruning occurs only if it removes at least this number of tokens. This prevents small changes with little gain.
96
398
 
97
- Merges, pushes, and tag creation never publish. The manual workflow requires an existing stable-version tag, matching manifests and release notes, and successful CI on its exact commit. That commit must belong to `main`. The dispatch ref and input tag must match. Running from the tag keeps npm provenance tied to the selected commit.
399
+ - `20000` (default).
400
+
401
+ ```json
402
+ { "contextKit": { "prune": { "minSavings": 10000 } } }
403
+ ```
404
+
405
+ ### `prune.minTokens`
406
+
407
+ Tool outputs smaller than this number of tokens are never pruned. A notice would not be much smaller than these outputs.
408
+
409
+ - `50` (default).
410
+
411
+ ```json
412
+ { "contextKit": { "prune": { "minTokens": 200 } } }
413
+ ```
414
+
415
+ ### `shake.protectTokens`
416
+
417
+ The newest part of the context, up to this number of tokens, is never shaken. Your own messages are never shaken, also when they are old.
418
+
419
+ - `16000` (default).
420
+
421
+ ```json
422
+ { "contextKit": { "shake": { "protectTokens": 32000 } } }
423
+ ```
424
+
425
+ ### `shake.minSavings`
426
+
427
+ Shaking occurs only if it removes at least this number of tokens.
428
+
429
+ - `4000` (default).
430
+
431
+ ```json
432
+ { "contextKit": { "shake": { "minSavings": 8000 } } }
433
+ ```
98
434
 
99
- The workflow tests and publishes that commit, not the current tip of `main`, then creates the GitHub release. A new npm publication updates the `latest` dist-tag.
435
+ ### `shake.blockMinTokens`
100
436
 
101
- If publication fails, fix the cause and use **Re-run failed jobs** on the original run, with the same tag. An existing npm version must have the same source commit; mismatches fail instead of overwriting a release. For code changes, prepare a new version and tag. npm can take time to make an accepted publication visible.
437
+ Code blocks and XML blocks smaller than this number of tokens are never shaken.
438
+
439
+ - `400` (default).
440
+
441
+ ```json
442
+ { "contextKit": { "shake": { "blockMinTokens": 1000 } } }
443
+ ```
444
+
445
+ There is no `shake.enabled` setting. To stop shaking, remove `"shake"` from `methodOrder`.
446
+
447
+ ### Pi settings that also apply
448
+
449
+ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block, next to the `contextKit` block.
450
+
451
+ | Pi setting | Default | Effect on pi-context-kit |
452
+ | --- | --- | --- |
453
+ | `compaction.enabled` | `true` | `false` stops Pi's automatic compaction. Then pi-context-kit changes the context only on `/compact`, because there is no threshold. |
454
+ | `compaction.reserveTokens` | `16384` | Pi's limit is the context window minus this number. pi-context-kit always starts at this limit or before. |
455
+ | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
456
+ | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
457
+
458
+ pi-context-kit has no setting per model. To start earlier for one model only, make Pi's limit smaller for this model with `compaction.modelOverrides`. pi-context-kit always starts at Pi's limit or before, so it also starts earlier for this model.
459
+
460
+ Example: all models start at 150,000 tokens. One model with a 200,000-token window starts at 200,000 − 80,000 = 120,000 tokens. Replace `provider/model-id` with the ID of your model.
461
+
462
+ ```json
463
+ {
464
+ "compaction": {
465
+ "modelOverrides": {
466
+ "provider/model-id": { "reserveTokens": 80000 }
467
+ }
468
+ },
469
+ "contextKit": {
470
+ "thresholdTokens": 150000
471
+ }
472
+ }
473
+ ```
474
+
475
+ Pi also uses `reserveTokens` to limit the length of its own summary. See the Pi documentation about compaction.
476
+
477
+ The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`.
478
+
479
+ ## Recipes
480
+
481
+ | I want to... | Settings |
482
+ | --- | --- |
483
+ | Start earlier with large models | `{ "contextKit": { "thresholdTokens": 150000 } }` |
484
+ | Use the same proportion for all models | `{ "contextKit": { "thresholdPercent": 75 } }` |
485
+ | Never write a handoff note | `{ "contextKit": { "methodOrder": ["shake", "soft"] } }` |
486
+ | Try the free method first, then a handoff note | `{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }` |
487
+ | Keep more recent tool outputs | `{ "contextKit": { "prune": { "protectTokens": 80000 } } }` |
488
+ | Keep all old file copies | `{ "contextKit": { "supersedeReads": false } }` |
489
+ | Use other settings in one project | Put the `contextKit` block in `.pi/settings.json` in that project. |
490
+ | Turn pi-context-kit off, but keep `recall` | `{ "contextKit": { "enabled": false } }` |
491
+
492
+ To combine recipes, put all the settings in one `contextKit` block:
493
+
494
+ ```json
495
+ {
496
+ "contextKit": {
497
+ "thresholdTokens": 150000,
498
+ "methodOrder": ["shake", "handoff", "soft"],
499
+ "prune": { "protectTokens": 80000 }
500
+ }
501
+ }
502
+ ```
503
+
504
+ ## Limits
505
+
506
+ - **Pi still has its own limit.** Pi compacts when the context reaches the context window minus `compaction.reserveTokens` (default 16,384). pi-context-kit can only start earlier, not later. You set Pi's limit with `compaction.reserveTokens` and `compaction.modelOverrides`.
507
+ - **A threshold is not a guarantee.** At the threshold, pi-context-kit tries to make the context smaller. If one tool output is very large, or the summary request fails, the methods can fail. Then Pi compacts at its own limit.
508
+ - **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different.
509
+ - **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit changes the context only when you run `/compact`. Then it writes a handoff note, as with compaction on. `thresholdTokens` and `thresholdPercent` are ignored, because pi-context-kit edits the context automatically only at a threshold.
510
+ - **Manual compaction and errors.** When you type `/compact`, when the context is too large for the model, or when Pi compacts before a turn, `shake` cannot run. pi-context-kit uses a ready handoff note, or Pi's summary.
511
+ - **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
512
+ - **Subagents** use their own settings. They show no warnings, because they have no screen.
513
+
514
+ ## Questions
515
+
516
+ **Does it slow down my work?**
517
+ Usually not. The handoff note is written in the background, and pruning and shaking do not use the model.
518
+ If no note is ready at the threshold, pi-context-kit can postpone the handoff until the note in progress is ready. It can also write a new note, which adds one model request.
519
+
520
+ **Does it cost more?**
521
+ A handoff note is one extra model request. It uses the same model, thinking level, and tool choice as your session. With Anthropic, this lets the provider reuse the cached conversation. Caching is not guaranteed.
522
+
523
+ **What happens if the handoff note fails?**
524
+ Pi shows a warning that starts with `pi-context-kit: handoff note failed`. Then pi-context-kit uses the next method, or Pi's summary. After a failed note at the threshold, pi-context-kit does not try a new note at the threshold again before the next compaction.
525
+
526
+ **Can I give a focus to a summary?**
527
+ Yes. Type `/compact` and the focus, for example `/compact keep the database migration details`. If enough space is available, pi-context-kit writes a new note with this focus. If not, Pi writes its summary.
528
+
529
+ **The model forgot a detail. What can I do?**
530
+ Ask the model to use the `recall` tool, for example: "Use recall to find the error message from the first test run."
531
+
532
+ ## Development
533
+
534
+ ```sh
535
+ npm ci
536
+ npm run check
537
+ ```
538
+
539
+ The tests run offline with Pi's faux provider. They do not call a real model.
540
+ Development uses Pi `1.5.2`. The oldest supported version is Pi `1.0.3`. CI checks the locked dependencies on Node 22 and 24, and Pi `1.0.3` and latest Pi on Node 24.
541
+ Host-provided peer dependencies use `"*"`, as required by Pi's package guide. This is not a guarantee that every Pi version works.
542
+
543
+ ## Contributing and releases
102
544
 
103
- The workflow uses npm trusted publishing, so the repository stores no npm token. Configure the npm trusted publisher for this repository, `release.yml`, and the GitHub environment `npm`. Restrict that environment to tags `v*`, with the owner as its required reviewer and self-review allowed. The workflow checks that the tagged commit belongs to `main`. Protect `v*` tags from updates and deletion, with no bypass actors. Keep these repository protections enabled to preserve release identity across retries.
545
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks, pull requests and releases. Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
104
546
 
105
547
  ## License
106
548