pi-context-kit 0.3.2 → 0.4.1
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/CHANGELOG.md +44 -0
- package/README.md +129 -335
- package/context-kit.schema.json +106 -0
- package/extensions/index.ts +216 -28
- package/package.json +8 -5
- 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/CHANGELOG.md
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Pi shows the entries newer than your installed version after `pi update`.
|
|
4
|
+
|
|
5
|
+
## [0.4.1] - 2026-11-13
|
|
6
|
+
|
|
7
|
+
- The README has a quick start and a troubleshooting section. No change to the extension.
|
|
8
|
+
|
|
9
|
+
## [0.4.0] - 2026-11-13
|
|
10
|
+
|
|
11
|
+
- The footer shows how full the context is and when cleanup starts, for example `Context 62% · cleanup at 75%`.
|
|
12
|
+
- `/context-kit` opens a panel to turn cleanup on or off, and to choose when and how to clean up.
|
|
13
|
+
- Settings move to their own file: `~/.pi/agent/context-kit.json`, and `.pi/context-kit.json` in a trusted project. At the first start, the `contextKit` entry of Pi's `settings.json` moves there with the same behavior.
|
|
14
|
+
- The default threshold is now `75%`. Set `"threshold": "pi"` to wait for Pi's limit as before.
|
|
15
|
+
|
|
16
|
+
## [0.3.2] - 2026-11-11
|
|
17
|
+
|
|
18
|
+
- Documentation only.
|
|
19
|
+
|
|
20
|
+
## [0.3.1] - 2026-11-11
|
|
21
|
+
|
|
22
|
+
- Documentation and package metadata only.
|
|
23
|
+
|
|
24
|
+
## [0.3.0] - 2026-11-11
|
|
25
|
+
|
|
26
|
+
- Breaking: the `staleSuffixTokens` setting is removed. Remove it from your settings.
|
|
27
|
+
- Supports Pi 1.5. Pi 1.0.3 is still the oldest supported version.
|
|
28
|
+
- Requires Node.js 22.19 or later, as Pi does.
|
|
29
|
+
- pi-context-kit edits the context only at the threshold, in one batch, so the provider's prompt cache breaks less often.
|
|
30
|
+
- After a handoff note, shaking runs only when pruning is not enough.
|
|
31
|
+
- With Pi's compaction off, pi-context-kit changes the context only on `/compact`.
|
|
32
|
+
- Background handoff notes are cancelled after session-tree navigation.
|
|
33
|
+
|
|
34
|
+
## [0.2.1] - 2026-10-06
|
|
35
|
+
|
|
36
|
+
- The README explains each term, the steps of a session, and each setting.
|
|
37
|
+
|
|
38
|
+
## [0.2.0] - 2026-10-06
|
|
39
|
+
|
|
40
|
+
- Handoff notes use the session's thinking level and tool choice, so Anthropic can reuse the cached conversation.
|
|
41
|
+
- An earlier threshold compacts at the end of a turn, even when no handoff note is ready.
|
|
42
|
+
- Recall regex searches are bounded and can be cancelled.
|
|
43
|
+
- Handoff notes that are truncated, too large or that call a tool are rejected.
|
|
44
|
+
- A failed threshold note is not retried until the next compaction.
|
package/README.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
# pi-context-kit
|
|
1
|
+
# pi-context-kit: long Pi sessions that stay sharp
|
|
2
2
|
|
|
3
|
-
[](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/pi-context-kit)
|
|
5
|
+
[](https://pi.dev/packages/pi-context-kit)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](LICENSE)
|
|
6
8
|
|
|
7
9
|
Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). pi-context-kit clears stale file reads and old tool outputs out of the context window, writes the handoff summary in the background before Pi needs it, and keeps the original text of the current branch one `recall` search away.
|
|
8
10
|
|
|
@@ -10,7 +12,7 @@ Pi compaction and context management for the [Pi coding agent](https://github.co
|
|
|
10
12
|
pi install npm:pi-context-kit
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
Restart Pi.
|
|
15
|
+
Restart Pi. The defaults work without configuration.
|
|
14
16
|
|
|
15
17
|
## Why pi-context-kit
|
|
16
18
|
|
|
@@ -19,11 +21,12 @@ Restart Pi. That is all: the defaults work without configuration. Requirements:
|
|
|
19
21
|
- **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool.
|
|
20
22
|
- **Free where possible.** Replacing old reads, pruning and shaking do not call the model.
|
|
21
23
|
- **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.
|
|
24
|
+
- **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.
|
|
25
|
+
- **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
26
|
|
|
24
27
|
## What the model sees
|
|
25
28
|
|
|
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 [`
|
|
29
|
+
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
30
|
|
|
28
31
|
```diff
|
|
29
32
|
- <first read of src/app.ts, about 5,000 tokens>
|
|
@@ -74,45 +77,49 @@ In a long session, the conversation fills the context window. File reads and com
|
|
|
74
77
|
|
|
75
78
|
</details>
|
|
76
79
|
|
|
77
|
-
##
|
|
80
|
+
## Quick start
|
|
78
81
|
|
|
79
|
-
1.
|
|
80
|
-
2. Type this command and press Enter:
|
|
82
|
+
You need Pi 1.0.3 or later and Node.js 22.19 or later.
|
|
81
83
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
84
|
+
1. Install the package with the command above.
|
|
85
|
+
2. Restart Pi.
|
|
86
|
+
3. Look at the footer. It shows `Context 0% · cleanup at 75%` when the extension is active.
|
|
87
|
+
4. Work as usual. Type `/context-kit` to change the settings.
|
|
85
88
|
|
|
86
|
-
|
|
89
|
+
## Update, try or remove
|
|
87
90
|
|
|
88
|
-
|
|
91
|
+
```sh
|
|
92
|
+
pi update npm:pi-context-kit # update, then restart Pi
|
|
93
|
+
pi -e npm:pi-context-kit # try for one session without installing
|
|
94
|
+
pi remove npm:pi-context-kit # remove, then restart Pi
|
|
95
|
+
```
|
|
89
96
|
|
|
90
|
-
|
|
97
|
+
After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
|
|
91
98
|
|
|
92
|
-
|
|
99
|
+
## Use it
|
|
93
100
|
|
|
94
|
-
|
|
101
|
+
You do not need to configure anything. pi-context-kit shows its state in Pi's footer:
|
|
95
102
|
|
|
96
|
-
|
|
97
|
-
|
|
103
|
+
| Footer | Meaning |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
|
|
106
|
+
| `Context 70% · cleanup at 75% · writing summary` | A handoff note is being written in the background. `summary ready` means that it is ready. |
|
|
107
|
+
| `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
|
|
108
|
+
| `Context cleanup off` | You turned automatic cleanup off. |
|
|
98
109
|
|
|
99
|
-
|
|
100
|
-
2. Add the `contextKit` block inside the outer `{ }`. Put a comma between this block and the other settings.
|
|
110
|
+
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.`
|
|
101
111
|
|
|
102
|
-
|
|
103
|
-
{
|
|
104
|
-
"contextKit": {
|
|
105
|
-
"thresholdTokens": 150000
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
```
|
|
112
|
+
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.
|
|
109
113
|
|
|
110
|
-
|
|
111
|
-
|
|
114
|
+
| Panel line | Choices | Setting in the file |
|
|
115
|
+
| --- | --- | --- |
|
|
116
|
+
| Automatic cleanup | On, Off | `enabled` |
|
|
117
|
+
| Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` |
|
|
118
|
+
| Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` |
|
|
112
119
|
|
|
113
|
-
|
|
120
|
+
The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
|
|
114
121
|
|
|
115
|
-
|
|
122
|
+
Outside the interactive mode, `/context-kit` shows the current settings in one line.
|
|
116
123
|
|
|
117
124
|
## How it works during a session
|
|
118
125
|
|
|
@@ -134,7 +141,7 @@ To use a setting only in one project, put the same block in the file `.pi/settin
|
|
|
134
141
|
|
|
|
135
142
|
no
|
|
136
143
|
v
|
|
137
|
-
Try each method
|
|
144
|
+
Try each method of the strategy, for example: handoff, shake, soft
|
|
138
145
|
```
|
|
139
146
|
|
|
140
147
|
### 1. Old file reads are replaced
|
|
@@ -161,7 +168,7 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
|
|
|
161
168
|
|
|
162
169
|
### 4. Other methods, in order
|
|
163
170
|
|
|
164
|
-
If pruning is not sufficient, pi-context-kit tries the methods
|
|
171
|
+
If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other:
|
|
165
172
|
|
|
166
173
|
| Method | What it does | Uses the model? |
|
|
167
174
|
| --- | --- | --- |
|
|
@@ -195,298 +202,105 @@ Compaction is different: it replaces older context with a summary, including old
|
|
|
195
202
|
|
|
196
203
|
## Settings
|
|
197
204
|
|
|
198
|
-
This section
|
|
205
|
+
This section is for users who edit the settings file. The panel changes the three main settings; the file also has the advanced settings.
|
|
199
206
|
|
|
200
|
-
###
|
|
201
|
-
|
|
202
|
-
Put all settings in a `contextKit` block, in one of these files:
|
|
207
|
+
### The settings files
|
|
203
208
|
|
|
204
209
|
| File | Applies to |
|
|
205
210
|
| --- | --- |
|
|
206
|
-
| `~/.pi/agent/
|
|
207
|
-
| `.pi/
|
|
208
|
-
|
|
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.
|
|
211
|
+
| `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. |
|
|
212
|
+
| `.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. |
|
|
211
213
|
|
|
212
|
-
|
|
214
|
+
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.
|
|
213
215
|
|
|
214
|
-
|
|
215
|
-
Copy only the lines that you want to change.
|
|
216
|
+
Add the `$schema` line to get completion and checks in editors such as VS Code:
|
|
216
217
|
|
|
217
218
|
```json
|
|
218
219
|
{
|
|
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
|
-
}
|
|
220
|
+
"$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
|
|
221
|
+
"threshold": "70%",
|
|
222
|
+
"strategy": "frugal"
|
|
239
223
|
}
|
|
240
224
|
```
|
|
241
225
|
|
|
242
|
-
###
|
|
226
|
+
### Main settings
|
|
243
227
|
|
|
244
|
-
| Setting | Allowed values | Default |
|
|
228
|
+
| Setting | Allowed values | Default | What it does |
|
|
245
229
|
| --- | --- | --- | --- |
|
|
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
|
-
```
|
|
230
|
+
| `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. |
|
|
231
|
+
| `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. |
|
|
232
|
+
| `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. |
|
|
272
233
|
|
|
273
|
-
A
|
|
234
|
+
**`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
235
|
|
|
275
|
-
|
|
236
|
+
**`strategy`.**
|
|
276
237
|
|
|
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 |
|
|
238
|
+
| Strategy (panel name) | Above the threshold, after pruning | Background requests |
|
|
303
239
|
| --- | --- | --- |
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
240
|
+
| `"balanced"` (Summary notes) | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. |
|
|
241
|
+
| `"frugal"` (Trim first) | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No |
|
|
242
|
+
| `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking. | No |
|
|
307
243
|
|
|
308
|
-
###
|
|
244
|
+
### Advanced settings
|
|
309
245
|
|
|
310
|
-
|
|
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.
|
|
314
|
-
|
|
315
|
-
pi-context-kit ignores this setting when `thresholdTokens` is not `-1`.
|
|
316
|
-
|
|
317
|
-
Example: start at 75% of the context window.
|
|
246
|
+
Put these settings in an `advanced` block. Most users never need them.
|
|
318
247
|
|
|
319
248
|
```json
|
|
320
|
-
{
|
|
249
|
+
{
|
|
250
|
+
"advanced": {
|
|
251
|
+
"methodOrder": ["handoff", "shake", "soft"],
|
|
252
|
+
"background": true,
|
|
253
|
+
"supersedeReads": true,
|
|
254
|
+
"progressRatio": 0.8,
|
|
255
|
+
"prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 },
|
|
256
|
+
"shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 }
|
|
257
|
+
}
|
|
258
|
+
}
|
|
321
259
|
```
|
|
322
260
|
|
|
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? |
|
|
261
|
+
| Setting | Default | What it does |
|
|
338
262
|
| --- | --- | --- |
|
|
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.
|
|
263
|
+
| `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. |
|
|
264
|
+
| `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. |
|
|
265
|
+
| `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. |
|
|
266
|
+
| `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. |
|
|
267
|
+
| `prune.enabled` | `true` | `false` never prunes tool outputs. |
|
|
268
|
+
| `prune.protectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. |
|
|
269
|
+
| `prune.minSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. |
|
|
270
|
+
| `prune.minTokens` | `50` | Tool outputs smaller than this are never pruned. |
|
|
271
|
+
| `shake.protectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. |
|
|
272
|
+
| `shake.minSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. |
|
|
273
|
+
| `shake.blockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. |
|
|
365
274
|
|
|
366
|
-
|
|
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.
|
|
391
|
-
|
|
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.
|
|
275
|
+
### When a setting is incorrect
|
|
468
276
|
|
|
469
|
-
- `
|
|
277
|
+
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
278
|
|
|
471
|
-
```
|
|
472
|
-
|
|
279
|
+
```text
|
|
280
|
+
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
281
|
```
|
|
474
282
|
|
|
475
|
-
|
|
283
|
+
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
284
|
|
|
477
|
-
|
|
285
|
+
### Upgrade from 0.3
|
|
478
286
|
|
|
479
|
-
|
|
287
|
+
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
288
|
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
289
|
+
| 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit.json`) |
|
|
290
|
+
| --- | --- |
|
|
291
|
+
| `thresholdTokens: 150000` | `threshold: 150000` |
|
|
292
|
+
| `thresholdPercent: 75` | `threshold: "75%"` |
|
|
293
|
+
| Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens |
|
|
294
|
+
| No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. |
|
|
295
|
+
| `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `advanced.background: true` unless `asyncEnabled` was `false` |
|
|
296
|
+
| `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
|
|
297
|
+
| 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. |
|
|
298
|
+
| `asyncEnabled` | `advanced.background`, when it differs from the strategy |
|
|
299
|
+
| `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced` |
|
|
486
300
|
|
|
487
301
|
### Pi settings that also apply
|
|
488
302
|
|
|
489
|
-
These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block
|
|
303
|
+
These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`.
|
|
490
304
|
|
|
491
305
|
| Pi setting | Default | Effect on pi-context-kit |
|
|
492
306
|
| --- | --- | --- |
|
|
@@ -495,61 +309,41 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction`
|
|
|
495
309
|
| `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
|
|
496
310
|
| `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
|
|
497
311
|
|
|
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`.
|
|
312
|
+
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
313
|
|
|
519
314
|
## Recipes
|
|
520
315
|
|
|
521
|
-
| I want to... |
|
|
316
|
+
| I want to... | `context-kit.json` |
|
|
522
317
|
| --- | --- |
|
|
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
|
-
```
|
|
318
|
+
| Start later, at Pi's own limit | `{ "threshold": "pi" }` |
|
|
319
|
+
| Start at the same number of tokens on all models | `{ "threshold": 150000 }` |
|
|
320
|
+
| Avoid model requests when possible | `{ "strategy": "frugal" }` |
|
|
321
|
+
| Never write a handoff note | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` |
|
|
322
|
+
| Keep more recent tool outputs | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` |
|
|
323
|
+
| Keep all old file copies | `{ "advanced": { "supersedeReads": false } }` |
|
|
324
|
+
| Turn pi-context-kit off, but keep `recall` | `{ "enabled": false }`, or `/context-kit` |
|
|
543
325
|
|
|
544
326
|
## Limits
|
|
545
327
|
|
|
546
328
|
- **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
329
|
- **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
330
|
- **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. `
|
|
331
|
+
- **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
332
|
- **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**
|
|
333
|
+
- **The method order stops at `soft`.** The methods after `soft` do not run.
|
|
334
|
+
- **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.
|
|
335
|
+
|
|
336
|
+
## Troubleshooting
|
|
337
|
+
|
|
338
|
+
**No `Context` in the footer**: type `pi list` and check that it shows `npm:pi-context-kit`. Then restart Pi. Pi shows the footer only in the interactive mode.
|
|
339
|
+
|
|
340
|
+
**`pi-context-kit settings need attention`**: a value in a settings file is not valid. pi-context-kit uses the default for that value. Type `/context-kit` to see the problem, then correct the file or select a new value in the panel.
|
|
341
|
+
|
|
342
|
+
**`pi-context-kit moved its settings to ...`**: an earlier version kept the settings in Pi's `settings.json`. pi-context-kit copied them to its own file once. You can remove the `contextKit` entry from `settings.json`.
|
|
343
|
+
|
|
344
|
+
**`pi-context-kit: handoff note failed`**: the summary request failed. pi-context-kit uses the next method or Pi's summary, so your session continues. Check the model and your provider limits.
|
|
345
|
+
|
|
346
|
+
**The panel cannot save a value**: Pi shows `pi-context-kit:` and the file error. Check that you can write the settings file, then select the value again.
|
|
553
347
|
|
|
554
348
|
## FAQ
|
|
555
349
|
|