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 +98 -320
- package/context-kit.schema.json +106 -0
- package/extensions/index.ts +216 -28
- package/package.json +5 -2
- package/src/background.ts +31 -2
- package/src/config.ts +173 -99
- package/src/migrate.ts +135 -0
- package/src/panel.ts +89 -0
- package/src/settings-file.ts +153 -0
- package/src/status.ts +41 -0
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.
|
|
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 [`
|
|
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
|
-
##
|
|
95
|
+
## Use it
|
|
95
96
|
|
|
96
|
-
|
|
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
|
-
|
|
100
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
203
|
+
### The settings files
|
|
203
204
|
|
|
204
205
|
| File | Applies to |
|
|
205
206
|
| --- | --- |
|
|
206
|
-
| `~/.pi/agent/
|
|
207
|
-
| `.pi/
|
|
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
|
-
|
|
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
|
-
"
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
###
|
|
222
|
+
### Main settings
|
|
243
223
|
|
|
244
|
-
| Setting | Allowed values | Default |
|
|
224
|
+
| Setting | Allowed values | Default | What it does |
|
|
245
225
|
| --- | --- | --- | --- |
|
|
246
|
-
|
|
|
247
|
-
|
|
|
248
|
-
|
|
|
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
|
|
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
|
-
|
|
232
|
+
**`strategy`.**
|
|
276
233
|
|
|
277
|
-
|
|
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
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
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
|
-
|
|
240
|
+
### Advanced settings
|
|
316
241
|
|
|
317
|
-
|
|
242
|
+
Put these settings in an `advanced` block. Most users never need them.
|
|
318
243
|
|
|
319
244
|
```json
|
|
320
|
-
{
|
|
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
|
-
|
|
|
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
|
-
| `
|
|
340
|
-
| `
|
|
341
|
-
| `
|
|
342
|
-
| `
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
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
|
-
```
|
|
472
|
-
|
|
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
|
-
|
|
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
|
-
|
|
281
|
+
### Upgrade from 0.3
|
|
478
282
|
|
|
479
|
-
|
|
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
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
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
|
|
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`.
|
|
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... |
|
|
312
|
+
| I want to... | `context-kit.json` |
|
|
522
313
|
| --- | --- |
|
|
523
|
-
| Start
|
|
524
|
-
|
|
|
525
|
-
|
|
|
526
|
-
|
|
|
527
|
-
| Keep more recent tool outputs | `{ "
|
|
528
|
-
| Keep all old file copies | `{ "
|
|
529
|
-
|
|
|
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. `
|
|
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
|
-
-
|
|
552
|
-
- **Subagents**
|
|
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
|
+
}
|