pi-context-kit 0.3.2 → 0.4.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
@@ -19,11 +19,12 @@ Restart Pi. That is all: the defaults work without configuration. Requirements:
19
19
  - **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool.
20
20
  - **Free where possible.** Replacing old reads, pruning and shaking do not call the model.
21
21
  - **Cache-friendly.** Context edits happen only above the threshold, in one batch. The provider's prompt cache breaks once per maintenance step, not at each turn.
22
- - **Zero setup.** Install, restart, work. Tune it later if you want.
22
+ - **Zero setup.** Install, restart, work. By default, maintenance starts at 75% of the context window, which for most models is before Pi's own limit.
23
+ - **Visible.** The footer shows how full the context is and when cleanup starts. A notice tells you what was freed. Type `/context-kit` to change the main settings in a panel, without editing a file.
23
24
 
24
25
  ## What the model sees
25
26
 
26
- Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`methodOrder`](#methodorder)):
27
+ Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`strategy`](#main-settings)):
27
28
 
28
29
  ```diff
29
30
  - <first read of src/app.ts, about 5,000 tokens>
@@ -91,28 +92,30 @@ To update, type `pi update npm:pi-context-kit` and restart Pi.
91
92
 
92
93
  To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
93
94
 
94
- ## Recommended setup
95
+ ## Use it
95
96
 
96
- The default setup works without changes. By default, maintenance starts at the same time as Pi's compaction.
97
- For large context windows, start maintenance earlier. This example starts at 150,000 tokens:
97
+ You do not need to configure anything. pi-context-kit shows its state in Pi's footer:
98
98
 
99
- 1. Open the file `~/.pi/agent/settings.json` in a text editor. `~` is your home folder.
100
- 2. Add the `contextKit` block inside the outer `{ }`. Put a comma between this block and the other settings.
99
+ | Footer | Meaning |
100
+ | --- | --- |
101
+ | `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
102
+ | `Context 70% · cleanup at 75% · writing summary` | A handoff note is being written in the background. `summary ready` means that it is ready. |
103
+ | `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
104
+ | `Context cleanup off` | You turned automatic cleanup off. |
101
105
 
102
- ```json
103
- {
104
- "contextKit": {
105
- "thresholdTokens": 150000
106
- }
107
- }
108
- ```
106
+ After pi-context-kit shortens old outputs, Pi shows a notice, for example: `pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.`
109
107
 
110
- 3. Save the file.
111
- 4. In Pi, type `/reload`, or restart Pi.
108
+ To change the settings, type `/context-kit` and press Enter. Select a line with the arrow keys and press Enter to change its value. The change is saved at once and applies from the next turn. Press Escape to close the panel.
112
109
 
113
- 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.
110
+ | Panel line | Choices | Setting in the file |
111
+ | --- | --- | --- |
112
+ | Automatic cleanup | On, Off | `enabled` |
113
+ | Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` |
114
+ | Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` |
114
115
 
115
- 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.
116
+ The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
117
+
118
+ Outside the interactive mode, `/context-kit` shows the current settings in one line.
116
119
 
117
120
  ## How it works during a session
118
121
 
@@ -134,7 +137,7 @@ To use a setting only in one project, put the same block in the file `.pi/settin
134
137
  |
135
138
  no
136
139
  v
137
- Try each method in "methodOrder": handoff, shake, soft
140
+ Try each method of the strategy, for example: handoff, shake, soft
138
141
  ```
139
142
 
140
143
  ### 1. Old file reads are replaced
@@ -161,7 +164,7 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
161
164
 
162
165
  ### 4. Other methods, in order
163
166
 
164
- If pruning is not sufficient, pi-context-kit tries the methods in `methodOrder`, one after the other:
167
+ If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other:
165
168
 
166
169
  | Method | What it does | Uses the model? |
167
170
  | --- | --- | --- |
@@ -195,298 +198,105 @@ Compaction is different: it replaces older context with a summary, including old
195
198
 
196
199
  ## Settings
197
200
 
198
- This section lists every setting. Each setting has its allowed values, its default, and an example.
199
-
200
- ### Where to put the settings
201
+ This section is for users who edit the settings file. The panel changes the three main settings; the file also has the advanced settings.
201
202
 
202
- Put all settings in a `contextKit` block, in one of these files:
203
+ ### The settings files
203
204
 
204
205
  | File | Applies to |
205
206
  | --- | --- |
206
- | `~/.pi/agent/settings.json` | All your projects. `~` is your home folder. |
207
- | `.pi/settings.json` in a project folder | Only this project. These values replace the values of the global file. |
207
+ | `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. |
208
+ | `.pi/context-kit.json` in a project folder | Only this project, and only when you trust the project in Pi. Its values replace the values of the global file. |
208
209
 
209
- You do not need to set all settings. A missing setting uses its default.
210
- After a change, type `/reload` in Pi, or restart Pi.
210
+ You do not need to set all settings. A missing setting uses its default. pi-context-kit reads the files again at each turn, so you do not need to restart Pi. The panel writes to the project file when that file sets the setting, otherwise to the global file.
211
211
 
212
- ### All settings with their defaults
213
-
214
- This block sets every setting to its default. It has the same effect as no `contextKit` block.
215
- Copy only the lines that you want to change.
212
+ Add the `$schema` line to get completion and checks in editors such as VS Code:
216
213
 
217
214
  ```json
218
215
  {
219
- "contextKit": {
220
- "enabled": true,
221
- "thresholdTokens": -1,
222
- "thresholdPercent": -1,
223
- "methodOrder": ["handoff", "shake", "soft"],
224
- "asyncEnabled": true,
225
- "supersedeReads": true,
226
- "progressRatio": 0.8,
227
- "prune": {
228
- "enabled": true,
229
- "protectTokens": 40000,
230
- "minSavings": 20000,
231
- "minTokens": 50
232
- },
233
- "shake": {
234
- "protectTokens": 16000,
235
- "minSavings": 4000,
236
- "blockMinTokens": 400
237
- }
238
- }
216
+ "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
217
+ "threshold": "70%",
218
+ "strategy": "frugal"
239
219
  }
240
220
  ```
241
221
 
242
- ### Summary table
222
+ ### Main settings
243
223
 
244
- | Setting | Allowed values | Default | Short description |
224
+ | Setting | Allowed values | Default | What it does |
245
225
  | --- | --- | --- | --- |
246
- | [`enabled`](#enabled) | `true`, `false` | `true` | Turns all maintenance on or off. |
247
- | [`thresholdTokens`](#thresholdtokens) | `-1`, or a whole number above 0 | `-1` | Starts maintenance at this number of tokens. |
248
- | [`thresholdPercent`](#thresholdpercent) | `-1`, or a number above 0, up to 100 | `-1` | Starts maintenance at this percentage of the context window. |
249
- | [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. |
250
- | [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. |
251
- | [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. |
252
- | [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. |
253
- | [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. |
254
- | [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. |
255
- | [`prune.minSavings`](#pruneminsavings) | A whole number, 0 or more | `20000` | The minimum gain for pruning. |
256
- | [`prune.minTokens`](#prunemintokens) | A whole number, 0 or more | `50` | Tool outputs smaller than this are never pruned. |
257
- | [`shake.protectTokens`](#shakeprotecttokens) | A whole number, 0 or more | `16000` | The newest context that is never shaken. |
258
- | [`shake.minSavings`](#shakeminsavings) | A whole number, 0 or more | `4000` | The minimum gain for shaking. |
259
- | [`shake.blockMinTokens`](#shakeblockmintokens) | A whole number, 0 or more | `400` | Blocks smaller than this are never shaken. |
260
-
261
- "Whole number" means a number without decimals, for example `150000`. Do not put spaces, dots, or commas in numbers: write `150000`, not `150,000`.
262
-
263
- ### When a setting is incorrect
264
-
265
- 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.
266
-
267
- Example: with `"thresholdTokens": "150000"` (a text in quotes, not a number), Pi shows:
268
-
269
- ```text
270
- pi-context-kit: invalid settings, defaults used (contextKit.thresholdTokens must be -1 or a positive integer).
271
- ```
226
+ | `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. |
227
+ | `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. |
228
+ | `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. |
272
229
 
273
- A setting name with a spelling mistake also shows a warning, for example `contextKit.treshold is not a setting`.
230
+ **`threshold`.** A percentage applies to each model's context window, so `"75%"` is 150,000 tokens with a 200,000-token window and 750,000 tokens with a 1,000,000-token window. Decimals are allowed, for example `"72.5%"`. A number such as `150000` is the same for all models. Do not put spaces, dots or commas in a number of tokens. `"pi"` waits for Pi's own limit. pi-context-kit can start before Pi's limit, never after: if your value is larger, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply).
274
231
 
275
- ### `enabled`
232
+ **`strategy`.**
276
233
 
277
- Turns all maintenance on or off.
278
-
279
- - `true` (default): pi-context-kit works as described in this document.
280
- - `false`: pi-context-kit does nothing. Pi uses only its own summary. The `recall` tool stays available.
281
-
282
- ```json
283
- { "contextKit": { "enabled": false } }
284
- ```
285
-
286
- ### `thresholdTokens`
287
-
288
- Maintenance starts when the context is larger than this number of tokens.
289
-
290
- - `-1` (default): use `thresholdPercent`. If `thresholdPercent` is also `-1`, use Pi's limit.
291
- - A whole number above 0: start at this number of tokens.
292
-
293
- This setting has priority over `thresholdPercent`.
294
- 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).
295
-
296
- Example: start at 150,000 tokens.
297
-
298
- ```json
299
- { "contextKit": { "thresholdTokens": 150000 } }
300
- ```
301
-
302
- | Model context window | Pi's limit (default reserve) | Threshold used |
234
+ | Strategy (panel name) | Above the threshold, after pruning | Background requests |
303
235
  | --- | --- | --- |
304
- | 1,000,000 | 983,616 | 150,000 |
305
- | 200,000 | 183,616 | 150,000 |
306
- | 128,000 | 111,616 | 111,616 (Pi's limit is smaller) |
307
-
308
- ### `thresholdPercent`
309
-
310
- Maintenance starts when the context is larger than this percentage of the model's context window.
311
-
312
- - `-1` (default): no percentage. If `thresholdTokens` is also `-1`, use Pi's limit.
313
- - 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.
236
+ | `"balanced"` (Summary notes) | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. |
237
+ | `"frugal"` (Trim first) | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No |
238
+ | `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking. | No |
314
239
 
315
- pi-context-kit ignores this setting when `thresholdTokens` is not `-1`.
240
+ ### Advanced settings
316
241
 
317
- Example: start at 75% of the context window.
242
+ Put these settings in an `advanced` block. Most users never need them.
318
243
 
319
244
  ```json
320
- { "contextKit": { "thresholdPercent": 75 } }
245
+ {
246
+ "advanced": {
247
+ "methodOrder": ["handoff", "shake", "soft"],
248
+ "background": true,
249
+ "supersedeReads": true,
250
+ "progressRatio": 0.8,
251
+ "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 },
252
+ "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 }
253
+ }
254
+ }
321
255
  ```
322
256
 
323
- | Model context window | Threshold used |
324
- | --- | --- |
325
- | 1,000,000 | 750,000 |
326
- | 200,000 | 150,000 |
327
- | 128,000 | 96,000 |
328
-
329
- 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.
330
-
331
- ### `methodOrder`
332
-
333
- The methods that pi-context-kit tries when pruning is not sufficient, in this order.
334
-
335
- Allowed values in the list:
336
-
337
- | Value | What it does | Calls the model? |
257
+ | Setting | Default | What it does |
338
258
  | --- | --- | --- |
339
- | `"handoff"` | Replaces the old conversation with a handoff note. The newest messages stay. | Yes, the session model |
340
- | `"shake"` | Replaces large old code blocks, XML blocks, and images with a short notice. | No |
341
- | `"soft"` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops the list. | Yes, the session model |
342
- | `"remote"`, `"snapcompact"` | Accepted for oh-my-pi compatibility, but skipped. Pi does not have these methods. | No |
343
-
344
- Rules:
345
-
346
- - The order is important. pi-context-kit tries the first method, then the next one.
347
- - `"soft"` ends the list. Methods after `"soft"` never run.
348
- - 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.
349
- - If `"shake"` is not in the list before `"soft"`, nothing is shaken.
350
- - A value that appears two times is used one time.
351
- - An empty list `[]` is allowed. Then pi-context-kit only replaces old file reads and prunes old tool outputs.
352
-
353
- Common choices:
354
-
355
- | `methodOrder` | What happens above the threshold |
356
- | --- | --- |
357
- | `["handoff", "shake", "soft"]` (default) | Prune. Then a handoff note. If the note fails, shake. Then Pi's summary. |
358
- | `["shake", "handoff", "soft"]` | Prune and shake together. If that is not sufficient, a handoff note. Then Pi's summary. |
359
- | `["handoff", "soft"]` | Prune. Then a handoff note. Never shake. |
360
- | `["shake", "soft"]` | Prune and shake. Then Pi's summary. No handoff note. |
361
- | `["soft"]` | Prune. Then Pi's summary. |
362
- | `[]` | Prune only. Pi writes its summary when the context reaches Pi's limit. |
363
-
364
- Example: try shaking first, because it does not call the model.
365
-
366
- ```json
367
- { "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }
368
- ```
369
-
370
- ### `asyncEnabled`
371
-
372
- Prepares the handoff note in the background, before the threshold.
373
-
374
- - `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. If the note is ready at the threshold, compaction is fast.
375
- - `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
376
-
377
- This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`.
378
-
379
- Example: no background requests.
380
-
381
- ```json
382
- { "contextKit": { "asyncEnabled": false } }
383
- ```
384
-
385
- ### `supersedeReads`
386
-
387
- Replaces the old copy of a file when the model reads the same file again.
388
-
389
- - `true` (default): the old copy becomes `[Superseded by a newer read of this file]`.
390
- - `false`: all copies stay.
259
+ | `methodOrder` | From `strategy` | Replaces the method order of the strategy. Allowed values: `"handoff"`, `"shake"`, `"soft"`. Methods after `"soft"` never run. Without `"handoff"` before `"soft"`, no handoff note is written, also on `/compact`. An empty list `[]` only replaces old reads and prunes. |
260
+ | `background` | From `strategy` | `true` writes the handoff note in the background, one eighth of the threshold early (maximum 32,000 tokens). `false` writes it at the threshold, and your work waits for it. |
261
+ | `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. |
262
+ | `progressRatio` | `0.8` | Each method must bring the context to this fraction of the threshold, otherwise its result is not used and the next method runs. Above 0, up to 1. |
263
+ | `prune.enabled` | `true` | `false` never prunes tool outputs. |
264
+ | `prune.protectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. |
265
+ | `prune.minSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. |
266
+ | `prune.minTokens` | `50` | Tool outputs smaller than this are never pruned. |
267
+ | `shake.protectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. |
268
+ | `shake.minSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. |
269
+ | `shake.blockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. |
391
270
 
392
- This works only above the threshold, together with pruning and shaking.
393
-
394
- ```json
395
- { "contextKit": { "supersedeReads": false } }
396
- ```
397
-
398
- ### `progressRatio`
399
-
400
- How small the context must become after a method, as a fraction of the threshold.
401
- If a method cannot make the context this small, pi-context-kit does not use its result and tries the next method.
402
-
403
- - `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.
404
- - A smaller value, for example `0.6`, gives more free space after maintenance. But each method must remove more, so it fails more often.
405
- - A larger value, for example `0.95`, makes each method succeed more easily. But maintenance can start again soon after.
406
-
407
- The value must be above 0 and not more than 1.
408
-
409
- ```json
410
- { "contextKit": { "progressRatio": 0.7 } }
411
- ```
412
-
413
- ### `prune.enabled`
414
-
415
- 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.]`.
416
-
417
- - `true` (default).
418
- - `false`: tool outputs are never pruned.
419
-
420
- ```json
421
- { "contextKit": { "prune": { "enabled": false } } }
422
- ```
423
-
424
- ### `prune.protectTokens`
425
-
426
- The newest tool outputs, up to this number of tokens, are never pruned. Thus the model keeps its most recent results.
427
-
428
- - `40000` (default).
429
- - A larger value keeps more recent outputs, but removes less.
430
-
431
- ```json
432
- { "contextKit": { "prune": { "protectTokens": 60000 } } }
433
- ```
434
-
435
- ### `prune.minSavings`
436
-
437
- Pruning occurs only if it removes at least this number of tokens. This prevents small changes with little gain.
438
-
439
- - `20000` (default).
440
-
441
- ```json
442
- { "contextKit": { "prune": { "minSavings": 10000 } } }
443
- ```
444
-
445
- ### `prune.minTokens`
446
-
447
- Tool outputs smaller than this number of tokens are never pruned. A notice would not be much smaller than these outputs.
448
-
449
- - `50` (default).
450
-
451
- ```json
452
- { "contextKit": { "prune": { "minTokens": 200 } } }
453
- ```
454
-
455
- ### `shake.protectTokens`
456
-
457
- 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.
458
-
459
- - `16000` (default).
460
-
461
- ```json
462
- { "contextKit": { "shake": { "protectTokens": 32000 } } }
463
- ```
464
-
465
- ### `shake.minSavings`
466
-
467
- Shaking occurs only if it removes at least this number of tokens.
271
+ ### When a setting is incorrect
468
272
 
469
- - `4000` (default).
273
+ 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. Example: with `"threshold": "150000"` (a text in quotes, not a number), Pi shows:
470
274
 
471
- ```json
472
- { "contextKit": { "shake": { "minSavings": 8000 } } }
275
+ ```text
276
+ pi-context-kit settings need attention: threshold must be a positive integer (tokens), a percentage such as "75%", or "pi" (default used). Type /context-kit to see them.
473
277
  ```
474
278
 
475
- ### `shake.blockMinTokens`
279
+ Pi also warns about a setting name with a spelling mistake, a file that is not valid JSON, and settings that have no effect, for example `advanced.background` without a handoff note in the method order.
476
280
 
477
- Code blocks and XML blocks smaller than this number of tokens are never shaken.
281
+ ### Upgrade from 0.3
478
282
 
479
- - `400` (default).
283
+ You do not need to do anything. Version 0.4 reads its own file. At the first start, it copies the `contextKit` block of Pi's `settings.json` to `~/.pi/agent/context-kit.json` (and the block of a trusted project to `.pi/context-kit.json`), with the same behavior, and shows a notice once. The project file gets only the settings that the project block changed, because 0.3 used the global block for the others. It does not change Pi's `settings.json`; you can delete the `contextKit` block, which is no longer used. If `context-kit.json` already exists, nothing is copied. If you had no `contextKit` block, 0.4 starts maintenance at the new default of `"75%"`; to wait for Pi's limit as before, set `"threshold": "pi"`. The table shows how the values are converted.
480
284
 
481
- ```json
482
- { "contextKit": { "shake": { "blockMinTokens": 1000 } } }
483
- ```
484
-
485
- There is no `shake.enabled` setting. To stop shaking, remove `"shake"` from `methodOrder`.
285
+ | 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit.json`) |
286
+ | --- | --- |
287
+ | `thresholdTokens: 150000` | `threshold: 150000` |
288
+ | `thresholdPercent: 75` | `threshold: "75%"` |
289
+ | Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens |
290
+ | No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. |
291
+ | `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `advanced.background: true` unless `asyncEnabled` was `false` |
292
+ | `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
293
+ | Other `methodOrder` values | `advanced.methodOrder`, without `"remote"` and `"snapcompact"`, which 0.3 already skipped. A list with an unknown method becomes the default order, as in 0.3. |
294
+ | `asyncEnabled` | `advanced.background`, when it differs from the strategy |
295
+ | `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced` |
486
296
 
487
297
  ### Pi settings that also apply
488
298
 
489
- These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block, next to the `contextKit` block.
299
+ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`.
490
300
 
491
301
  | Pi setting | Default | Effect on pi-context-kit |
492
302
  | --- | --- | --- |
@@ -495,61 +305,29 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction`
495
305
  | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
496
306
  | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
497
307
 
498
- 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.
499
-
500
- 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.
501
-
502
- ```json
503
- {
504
- "compaction": {
505
- "modelOverrides": {
506
- "provider/model-id": { "reserveTokens": 80000 }
507
- }
508
- },
509
- "contextKit": {
510
- "thresholdTokens": 150000
511
- }
512
- }
513
- ```
514
-
515
- Pi also uses `reserveTokens` to limit the length of its own summary. See the Pi documentation about compaction.
516
-
517
- The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`.
308
+ 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`, for example `{ "compaction": { "modelOverrides": { "provider/model-id": { "reserveTokens": 80000 } } } }`. With a 200,000-token window, this model then starts at 120,000 tokens at the latest. The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`.
518
309
 
519
310
  ## Recipes
520
311
 
521
- | I want to... | Settings |
312
+ | I want to... | `context-kit.json` |
522
313
  | --- | --- |
523
- | Start earlier with large models | `{ "contextKit": { "thresholdTokens": 150000 } }` |
524
- | Use the same proportion for all models | `{ "contextKit": { "thresholdPercent": 75 } }` |
525
- | Never write a handoff note | `{ "contextKit": { "methodOrder": ["shake", "soft"] } }` |
526
- | Try the free method first, then a handoff note | `{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }` |
527
- | Keep more recent tool outputs | `{ "contextKit": { "prune": { "protectTokens": 80000 } } }` |
528
- | Keep all old file copies | `{ "contextKit": { "supersedeReads": false } }` |
529
- | Use other settings in one project | Put the `contextKit` block in `.pi/settings.json` in that project. |
530
- | Turn pi-context-kit off, but keep `recall` | `{ "contextKit": { "enabled": false } }` |
531
-
532
- To combine recipes, put all the settings in one `contextKit` block:
533
-
534
- ```json
535
- {
536
- "contextKit": {
537
- "thresholdTokens": 150000,
538
- "methodOrder": ["shake", "handoff", "soft"],
539
- "prune": { "protectTokens": 80000 }
540
- }
541
- }
542
- ```
314
+ | Start later, at Pi's own limit | `{ "threshold": "pi" }` |
315
+ | Start at the same number of tokens on all models | `{ "threshold": 150000 }` |
316
+ | Avoid model requests when possible | `{ "strategy": "frugal" }` |
317
+ | Never write a handoff note | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` |
318
+ | Keep more recent tool outputs | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` |
319
+ | Keep all old file copies | `{ "advanced": { "supersedeReads": false } }` |
320
+ | Turn pi-context-kit off, but keep `recall` | `{ "enabled": false }`, or `/context-kit` |
543
321
 
544
322
  ## Limits
545
323
 
546
324
  - **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`.
547
325
  - **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.
548
326
  - **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different.
549
- - **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.
327
+ - **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. `threshold` is ignored, because pi-context-kit edits the context automatically only at a threshold.
550
328
  - **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.
551
- - **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
552
- - **Subagents** use their own settings. They show no warnings, because they have no screen.
329
+ - **The method order stops at `soft`.** The methods after `soft` do not run.
330
+ - **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.
553
331
 
554
332
  ## FAQ
555
333
 
@@ -0,0 +1,106 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
4
+ "title": "pi-context-kit settings",
5
+ "description": "~/.pi/agent/context-kit.json, or .pi/context-kit.json in a trusted project.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "$schema": { "type": "string" },
10
+ "enabled": {
11
+ "description": "false stops context maintenance and handoff notes. recall stays available.",
12
+ "type": "boolean",
13
+ "default": true
14
+ },
15
+ "threshold": {
16
+ "description": "Where maintenance starts: a number of tokens, a share of the context window such as \"75%\", or \"pi\" for Pi's own compaction threshold.",
17
+ "default": "75%",
18
+ "oneOf": [
19
+ { "type": "integer", "minimum": 1 },
20
+ { "type": "string", "pattern": "^(0*100(\\.0+)?|0*[1-9]\\d?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*)%$" },
21
+ { "const": "pi" }
22
+ ]
23
+ },
24
+ "strategy": {
25
+ "description": "balanced: handoff note written in the background, then shake, then Pi's summary. frugal: shake first, no background calls. pi-summary: Pi's summary only.",
26
+ "enum": ["balanced", "frugal", "pi-summary"],
27
+ "default": "balanced"
28
+ },
29
+ "advanced": {
30
+ "type": "object",
31
+ "additionalProperties": false,
32
+ "properties": {
33
+ "methodOrder": {
34
+ "description": "Replaces the method order of the strategy. Methods after \"soft\" never run.",
35
+ "type": "array",
36
+ "items": { "enum": ["handoff", "shake", "soft"] }
37
+ },
38
+ "background": {
39
+ "description": "Write the handoff note in the background before the threshold. The strategy sets the default.",
40
+ "type": "boolean"
41
+ },
42
+ "supersedeReads": {
43
+ "description": "Replace an older read of a file that was read again.",
44
+ "type": "boolean",
45
+ "default": true
46
+ },
47
+ "progressRatio": {
48
+ "description": "Each method must bring the context to this fraction of the threshold, or the next method runs.",
49
+ "type": "number",
50
+ "exclusiveMinimum": 0,
51
+ "maximum": 1,
52
+ "default": 0.8
53
+ },
54
+ "prune": {
55
+ "type": "object",
56
+ "additionalProperties": false,
57
+ "properties": {
58
+ "enabled": { "type": "boolean", "default": true },
59
+ "protectTokens": {
60
+ "description": "The newest tool outputs, up to this many tokens, are never pruned.",
61
+ "type": "integer",
62
+ "minimum": 0,
63
+ "default": 40000
64
+ },
65
+ "minSavings": {
66
+ "description": "Prune only when this many tokens or more are removed.",
67
+ "type": "integer",
68
+ "minimum": 0,
69
+ "default": 20000
70
+ },
71
+ "minTokens": {
72
+ "description": "Tool outputs smaller than this are never pruned.",
73
+ "type": "integer",
74
+ "minimum": 0,
75
+ "default": 50
76
+ }
77
+ }
78
+ },
79
+ "shake": {
80
+ "type": "object",
81
+ "additionalProperties": false,
82
+ "properties": {
83
+ "protectTokens": {
84
+ "description": "The newest context, up to this many tokens, is never shaken.",
85
+ "type": "integer",
86
+ "minimum": 0,
87
+ "default": 16000
88
+ },
89
+ "minSavings": {
90
+ "description": "Shake only when this many tokens or more are removed.",
91
+ "type": "integer",
92
+ "minimum": 0,
93
+ "default": 4000
94
+ },
95
+ "blockMinTokens": {
96
+ "description": "Code and XML blocks smaller than this are never shaken.",
97
+ "type": "integer",
98
+ "minimum": 0,
99
+ "default": 400
100
+ }
101
+ }
102
+ }
103
+ }
104
+ }
105
+ }
106
+ }