pi-context-kit 0.3.1 → 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 +140 -341
- 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
|
@@ -1,12 +1,43 @@
|
|
|
1
1
|
# pi-context-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/pi-context-kit) [](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [](https://nodejs.org) [](LICENSE)
|
|
4
|
+
|
|
5
|
+
**Long Pi sessions that stay sharp.**
|
|
6
|
+
|
|
7
|
+
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.
|
|
4
8
|
|
|
5
9
|
```sh
|
|
6
10
|
pi install npm:pi-context-kit
|
|
7
11
|
```
|
|
8
12
|
|
|
9
|
-
Restart Pi
|
|
13
|
+
Restart Pi. That is all: the defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
|
|
14
|
+
|
|
15
|
+
## Why pi-context-kit
|
|
16
|
+
|
|
17
|
+
- **A cleaner context window.** Above the threshold, old copies of files and old tool outputs become one-line notices. The newest tool outputs stay.
|
|
18
|
+
- **Summaries written ahead of time.** The session model writes the handoff note in the background, while it continues to work. When a ready note still fits at the threshold, compaction does not wait for a new summary.
|
|
19
|
+
- **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool.
|
|
20
|
+
- **Free where possible.** Replacing old reads, pruning and shaking do not call the model.
|
|
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. 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.
|
|
24
|
+
|
|
25
|
+
## What the model sees
|
|
26
|
+
|
|
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)):
|
|
28
|
+
|
|
29
|
+
```diff
|
|
30
|
+
- <first read of src/app.ts, about 5,000 tokens>
|
|
31
|
+
+ [Superseded by a newer read of this file]
|
|
32
|
+
|
|
33
|
+
- <output of npm test from one hour ago, about 12,000 tokens>
|
|
34
|
+
+ [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.]
|
|
35
|
+
|
|
36
|
+
- <a large code block in an old reply, about 2,000 tokens>
|
|
37
|
+
+ [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
These notices never change your messages or the model's tool calls. The model's reasoning also stays, with one exception for Anthropic. Compaction still replaces older messages with a summary. See [What maintenance preserves](#what-maintenance-preserves).
|
|
10
41
|
|
|
11
42
|
## Pi alone, and Pi with pi-context-kit
|
|
12
43
|
|
|
@@ -19,24 +50,16 @@ Restart Pi after the install. The defaults work without configuration. Requireme
|
|
|
19
50
|
|
|
20
51
|
The original session entries never change. Only the context that Pi sends to the model becomes smaller.
|
|
21
52
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
## The problem
|
|
25
|
-
|
|
26
|
-
An AI model can read only a limited amount of text at one time. This limit is the **context window**.
|
|
27
|
-
Text is measured in **tokens**. One token is approximately 3 to 4 characters of English text.
|
|
53
|
+
pi-context-kit is for long Pi sessions: many file reads, long command outputs, or many compactions. In a short session, the context rarely reaches the threshold. Then the context does not change at the end of a turn. A background handoff note can still start near the threshold, and `/compact` tries a handoff note first, with Pi's summary as the fallback.
|
|
28
54
|
|
|
29
|
-
|
|
30
|
-
When the window is almost full, Pi does a **compaction**: it replaces the old conversation with a summary.
|
|
31
|
-
A summary can lose details, and it costs time and money.
|
|
55
|
+
## Why long Pi sessions need context management
|
|
32
56
|
|
|
33
|
-
|
|
57
|
+
An AI model can read only a limited amount of text at one time. This limit is the **context window**. Text is measured in **tokens**. Pi counts approximately 4 characters as one token.
|
|
34
58
|
|
|
35
|
-
|
|
36
|
-
2. When a summary is necessary, it can prepare a handoff note in advance.
|
|
37
|
-
3. It leaves the original session entries unchanged. The model can retrieve earlier text on the current branch with `recall`.
|
|
59
|
+
In a long session, the conversation fills the context window. File reads and command outputs are usually the largest parts. When the window is almost full, Pi does a **compaction**: it replaces the old conversation with a summary. A summary can lose details, and it costs time and money.
|
|
38
60
|
|
|
39
|
-
|
|
61
|
+
<details>
|
|
62
|
+
<summary>Words used in this document</summary>
|
|
40
63
|
|
|
41
64
|
| Word | Meaning |
|
|
42
65
|
| --- | --- |
|
|
@@ -50,6 +73,8 @@ pi-context-kit does three things:
|
|
|
50
73
|
| Handoff note | A summary that pi-context-kit writes with the same model as your session. |
|
|
51
74
|
| Pi's summary | The summary that Pi writes when no handoff note is available. |
|
|
52
75
|
|
|
76
|
+
</details>
|
|
77
|
+
|
|
53
78
|
## Install
|
|
54
79
|
|
|
55
80
|
1. Open a terminal.
|
|
@@ -67,53 +92,52 @@ To update, type `pi update npm:pi-context-kit` and restart Pi.
|
|
|
67
92
|
|
|
68
93
|
To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
|
|
69
94
|
|
|
70
|
-
##
|
|
95
|
+
## Use it
|
|
71
96
|
|
|
72
|
-
|
|
73
|
-
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:
|
|
74
98
|
|
|
75
|
-
|
|
76
|
-
|
|
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. |
|
|
77
105
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
"thresholdTokens": 150000
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
```
|
|
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.`
|
|
107
|
+
|
|
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.
|
|
85
109
|
|
|
86
|
-
|
|
87
|
-
|
|
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"` |
|
|
88
115
|
|
|
89
|
-
|
|
116
|
+
The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
|
|
90
117
|
|
|
91
|
-
|
|
118
|
+
Outside the interactive mode, `/context-kit` shows the current settings in one line.
|
|
92
119
|
|
|
93
|
-
##
|
|
120
|
+
## How it works during a session
|
|
94
121
|
|
|
95
122
|
```text
|
|
96
123
|
Every turn ends
|
|
97
124
|
|
|
|
98
125
|
v
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
v
|
|
102
|
-
Context near the threshold? --yes--> 2. Start a handoff note in the background
|
|
126
|
+
Context near the threshold? --yes--> Start a handoff note in the background
|
|
103
127
|
|
|
|
104
128
|
v
|
|
105
129
|
Context above the threshold? --no--> continue to work
|
|
106
130
|
|
|
|
107
131
|
yes
|
|
108
132
|
v
|
|
109
|
-
|
|
133
|
+
Replace old file reads, and prune old tool outputs
|
|
110
134
|
|
|
|
111
135
|
v
|
|
112
136
|
Small enough now? --yes--> continue to work
|
|
113
137
|
|
|
|
114
138
|
no
|
|
115
139
|
v
|
|
116
|
-
|
|
140
|
+
Try each method of the strategy, for example: handoff, shake, soft
|
|
117
141
|
```
|
|
118
142
|
|
|
119
143
|
### 1. Old file reads are replaced
|
|
@@ -140,7 +164,7 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
|
|
|
140
164
|
|
|
141
165
|
### 4. Other methods, in order
|
|
142
166
|
|
|
143
|
-
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:
|
|
144
168
|
|
|
145
169
|
| Method | What it does | Uses the model? |
|
|
146
170
|
| --- | --- | --- |
|
|
@@ -174,298 +198,105 @@ Compaction is different: it replaces older context with a summary, including old
|
|
|
174
198
|
|
|
175
199
|
## Settings
|
|
176
200
|
|
|
177
|
-
This section
|
|
178
|
-
|
|
179
|
-
### 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.
|
|
180
202
|
|
|
181
|
-
|
|
203
|
+
### The settings files
|
|
182
204
|
|
|
183
205
|
| File | Applies to |
|
|
184
206
|
| --- | --- |
|
|
185
|
-
| `~/.pi/agent/
|
|
186
|
-
| `.pi/
|
|
187
|
-
|
|
188
|
-
You do not need to set all settings. A missing setting uses its default.
|
|
189
|
-
After a change, type `/reload` in Pi, or restart 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. |
|
|
190
209
|
|
|
191
|
-
|
|
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.
|
|
192
211
|
|
|
193
|
-
|
|
194
|
-
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:
|
|
195
213
|
|
|
196
214
|
```json
|
|
197
215
|
{
|
|
198
|
-
"
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
"thresholdPercent": -1,
|
|
202
|
-
"methodOrder": ["handoff", "shake", "soft"],
|
|
203
|
-
"asyncEnabled": true,
|
|
204
|
-
"supersedeReads": true,
|
|
205
|
-
"progressRatio": 0.8,
|
|
206
|
-
"prune": {
|
|
207
|
-
"enabled": true,
|
|
208
|
-
"protectTokens": 40000,
|
|
209
|
-
"minSavings": 20000,
|
|
210
|
-
"minTokens": 50
|
|
211
|
-
},
|
|
212
|
-
"shake": {
|
|
213
|
-
"protectTokens": 16000,
|
|
214
|
-
"minSavings": 4000,
|
|
215
|
-
"blockMinTokens": 400
|
|
216
|
-
}
|
|
217
|
-
}
|
|
216
|
+
"$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
|
|
217
|
+
"threshold": "70%",
|
|
218
|
+
"strategy": "frugal"
|
|
218
219
|
}
|
|
219
220
|
```
|
|
220
221
|
|
|
221
|
-
###
|
|
222
|
+
### Main settings
|
|
222
223
|
|
|
223
|
-
| Setting | Allowed values | Default |
|
|
224
|
+
| Setting | Allowed values | Default | What it does |
|
|
224
225
|
| --- | --- | --- | --- |
|
|
225
|
-
|
|
|
226
|
-
|
|
|
227
|
-
|
|
|
228
|
-
| [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. |
|
|
229
|
-
| [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. |
|
|
230
|
-
| [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. |
|
|
231
|
-
| [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. |
|
|
232
|
-
| [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. |
|
|
233
|
-
| [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. |
|
|
234
|
-
| [`prune.minSavings`](#pruneminsavings) | A whole number, 0 or more | `20000` | The minimum gain for pruning. |
|
|
235
|
-
| [`prune.minTokens`](#prunemintokens) | A whole number, 0 or more | `50` | Tool outputs smaller than this are never pruned. |
|
|
236
|
-
| [`shake.protectTokens`](#shakeprotecttokens) | A whole number, 0 or more | `16000` | The newest context that is never shaken. |
|
|
237
|
-
| [`shake.minSavings`](#shakeminsavings) | A whole number, 0 or more | `4000` | The minimum gain for shaking. |
|
|
238
|
-
| [`shake.blockMinTokens`](#shakeblockmintokens) | A whole number, 0 or more | `400` | Blocks smaller than this are never shaken. |
|
|
239
|
-
|
|
240
|
-
"Whole number" means a number without decimals, for example `150000`. Do not put spaces, dots, or commas in numbers: write `150000`, not `150,000`.
|
|
241
|
-
|
|
242
|
-
### When a setting is incorrect
|
|
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. |
|
|
243
229
|
|
|
244
|
-
|
|
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).
|
|
245
231
|
|
|
246
|
-
|
|
232
|
+
**`strategy`.**
|
|
247
233
|
|
|
248
|
-
|
|
249
|
-
pi-context-kit: invalid settings, defaults used (contextKit.thresholdTokens must be -1 or a positive integer).
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
A setting name with a spelling mistake also shows a warning, for example `contextKit.treshold is not a setting`.
|
|
253
|
-
|
|
254
|
-
### `enabled`
|
|
255
|
-
|
|
256
|
-
Turns all maintenance on or off.
|
|
257
|
-
|
|
258
|
-
- `true` (default): pi-context-kit works as described in this document.
|
|
259
|
-
- `false`: pi-context-kit does nothing. Pi uses only its own summary. The `recall` tool stays available.
|
|
260
|
-
|
|
261
|
-
```json
|
|
262
|
-
{ "contextKit": { "enabled": false } }
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
### `thresholdTokens`
|
|
266
|
-
|
|
267
|
-
Maintenance starts when the context is larger than this number of tokens.
|
|
268
|
-
|
|
269
|
-
- `-1` (default): use `thresholdPercent`. If `thresholdPercent` is also `-1`, use Pi's limit.
|
|
270
|
-
- A whole number above 0: start at this number of tokens.
|
|
271
|
-
|
|
272
|
-
This setting has priority over `thresholdPercent`.
|
|
273
|
-
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).
|
|
274
|
-
|
|
275
|
-
Example: start at 150,000 tokens.
|
|
276
|
-
|
|
277
|
-
```json
|
|
278
|
-
{ "contextKit": { "thresholdTokens": 150000 } }
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
| Model context window | Pi's limit (default reserve) | Threshold used |
|
|
234
|
+
| Strategy (panel name) | Above the threshold, after pruning | Background requests |
|
|
282
235
|
| --- | --- | --- |
|
|
283
|
-
|
|
|
284
|
-
|
|
|
285
|
-
|
|
|
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 |
|
|
286
239
|
|
|
287
|
-
###
|
|
240
|
+
### Advanced settings
|
|
288
241
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
- `-1` (default): no percentage. If `thresholdTokens` is also `-1`, use Pi's limit.
|
|
292
|
-
- 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.
|
|
293
|
-
|
|
294
|
-
pi-context-kit ignores this setting when `thresholdTokens` is not `-1`.
|
|
295
|
-
|
|
296
|
-
Example: start at 75% of the context window.
|
|
242
|
+
Put these settings in an `advanced` block. Most users never need them.
|
|
297
243
|
|
|
298
244
|
```json
|
|
299
|
-
{
|
|
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
|
+
}
|
|
300
255
|
```
|
|
301
256
|
|
|
302
|
-
|
|
|
303
|
-
| --- | --- |
|
|
304
|
-
| 1,000,000 | 750,000 |
|
|
305
|
-
| 200,000 | 150,000 |
|
|
306
|
-
| 128,000 | 96,000 |
|
|
307
|
-
|
|
308
|
-
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.
|
|
309
|
-
|
|
310
|
-
### `methodOrder`
|
|
311
|
-
|
|
312
|
-
The methods that pi-context-kit tries when pruning is not sufficient, in this order.
|
|
313
|
-
|
|
314
|
-
Allowed values in the list:
|
|
315
|
-
|
|
316
|
-
| Value | What it does | Calls the model? |
|
|
257
|
+
| Setting | Default | What it does |
|
|
317
258
|
| --- | --- | --- |
|
|
318
|
-
| `
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
- A value that appears two times is used one time.
|
|
330
|
-
- An empty list `[]` is allowed. Then pi-context-kit only replaces old file reads and prunes old tool outputs.
|
|
331
|
-
|
|
332
|
-
Common choices:
|
|
333
|
-
|
|
334
|
-
| `methodOrder` | What happens above the threshold |
|
|
335
|
-
| --- | --- |
|
|
336
|
-
| `["handoff", "shake", "soft"]` (default) | Prune. Then a handoff note. If the note fails, shake. Then Pi's summary. |
|
|
337
|
-
| `["shake", "handoff", "soft"]` | Prune and shake together. If that is not sufficient, a handoff note. Then Pi's summary. |
|
|
338
|
-
| `["handoff", "soft"]` | Prune. Then a handoff note. Never shake. |
|
|
339
|
-
| `["shake", "soft"]` | Prune and shake. Then Pi's summary. No handoff note. |
|
|
340
|
-
| `["soft"]` | Prune. Then Pi's summary. |
|
|
341
|
-
| `[]` | Prune only. Pi writes its summary when the context reaches Pi's limit. |
|
|
342
|
-
|
|
343
|
-
Example: try shaking first, because it does not call the model.
|
|
344
|
-
|
|
345
|
-
```json
|
|
346
|
-
{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
### `asyncEnabled`
|
|
350
|
-
|
|
351
|
-
Prepares the handoff note in the background, before the threshold.
|
|
352
|
-
|
|
353
|
-
- `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.
|
|
354
|
-
- `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
|
|
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. |
|
|
355
270
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
Example: no background requests.
|
|
359
|
-
|
|
360
|
-
```json
|
|
361
|
-
{ "contextKit": { "asyncEnabled": false } }
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
### `supersedeReads`
|
|
365
|
-
|
|
366
|
-
Replaces the old copy of a file when the model reads the same file again.
|
|
367
|
-
|
|
368
|
-
- `true` (default): the old copy becomes `[Superseded by a newer read of this file]`.
|
|
369
|
-
- `false`: all copies stay.
|
|
370
|
-
|
|
371
|
-
This works only above the threshold, together with pruning and shaking.
|
|
372
|
-
|
|
373
|
-
```json
|
|
374
|
-
{ "contextKit": { "supersedeReads": false } }
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
### `progressRatio`
|
|
378
|
-
|
|
379
|
-
How small the context must become after a method, as a fraction of the threshold.
|
|
380
|
-
If a method cannot make the context this small, pi-context-kit does not use its result and tries the next method.
|
|
381
|
-
|
|
382
|
-
- `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.
|
|
383
|
-
- A smaller value, for example `0.6`, gives more free space after maintenance. But each method must remove more, so it fails more often.
|
|
384
|
-
- A larger value, for example `0.95`, makes each method succeed more easily. But maintenance can start again soon after.
|
|
385
|
-
|
|
386
|
-
The value must be above 0 and not more than 1.
|
|
387
|
-
|
|
388
|
-
```json
|
|
389
|
-
{ "contextKit": { "progressRatio": 0.7 } }
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
### `prune.enabled`
|
|
393
|
-
|
|
394
|
-
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.]`.
|
|
395
|
-
|
|
396
|
-
- `true` (default).
|
|
397
|
-
- `false`: tool outputs are never pruned.
|
|
398
|
-
|
|
399
|
-
```json
|
|
400
|
-
{ "contextKit": { "prune": { "enabled": false } } }
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
### `prune.protectTokens`
|
|
404
|
-
|
|
405
|
-
The newest tool outputs, up to this number of tokens, are never pruned. Thus the model keeps its most recent results.
|
|
406
|
-
|
|
407
|
-
- `40000` (default).
|
|
408
|
-
- A larger value keeps more recent outputs, but removes less.
|
|
409
|
-
|
|
410
|
-
```json
|
|
411
|
-
{ "contextKit": { "prune": { "protectTokens": 60000 } } }
|
|
412
|
-
```
|
|
413
|
-
|
|
414
|
-
### `prune.minSavings`
|
|
415
|
-
|
|
416
|
-
Pruning occurs only if it removes at least this number of tokens. This prevents small changes with little gain.
|
|
417
|
-
|
|
418
|
-
- `20000` (default).
|
|
419
|
-
|
|
420
|
-
```json
|
|
421
|
-
{ "contextKit": { "prune": { "minSavings": 10000 } } }
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
### `prune.minTokens`
|
|
425
|
-
|
|
426
|
-
Tool outputs smaller than this number of tokens are never pruned. A notice would not be much smaller than these outputs.
|
|
427
|
-
|
|
428
|
-
- `50` (default).
|
|
429
|
-
|
|
430
|
-
```json
|
|
431
|
-
{ "contextKit": { "prune": { "minTokens": 200 } } }
|
|
432
|
-
```
|
|
433
|
-
|
|
434
|
-
### `shake.protectTokens`
|
|
435
|
-
|
|
436
|
-
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.
|
|
437
|
-
|
|
438
|
-
- `16000` (default).
|
|
439
|
-
|
|
440
|
-
```json
|
|
441
|
-
{ "contextKit": { "shake": { "protectTokens": 32000 } } }
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
### `shake.minSavings`
|
|
445
|
-
|
|
446
|
-
Shaking occurs only if it removes at least this number of tokens.
|
|
271
|
+
### When a setting is incorrect
|
|
447
272
|
|
|
448
|
-
- `
|
|
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:
|
|
449
274
|
|
|
450
|
-
```
|
|
451
|
-
|
|
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.
|
|
452
277
|
```
|
|
453
278
|
|
|
454
|
-
|
|
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.
|
|
455
280
|
|
|
456
|
-
|
|
281
|
+
### Upgrade from 0.3
|
|
457
282
|
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
```json
|
|
461
|
-
{ "contextKit": { "shake": { "blockMinTokens": 1000 } } }
|
|
462
|
-
```
|
|
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.
|
|
463
284
|
|
|
464
|
-
|
|
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` |
|
|
465
296
|
|
|
466
297
|
### Pi settings that also apply
|
|
467
298
|
|
|
468
|
-
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`.
|
|
469
300
|
|
|
470
301
|
| Pi setting | Default | Effect on pi-context-kit |
|
|
471
302
|
| --- | --- | --- |
|
|
@@ -474,63 +305,31 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction`
|
|
|
474
305
|
| `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
|
|
475
306
|
| `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
|
|
476
307
|
|
|
477
|
-
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`.
|
|
478
|
-
|
|
479
|
-
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.
|
|
480
|
-
|
|
481
|
-
```json
|
|
482
|
-
{
|
|
483
|
-
"compaction": {
|
|
484
|
-
"modelOverrides": {
|
|
485
|
-
"provider/model-id": { "reserveTokens": 80000 }
|
|
486
|
-
}
|
|
487
|
-
},
|
|
488
|
-
"contextKit": {
|
|
489
|
-
"thresholdTokens": 150000
|
|
490
|
-
}
|
|
491
|
-
}
|
|
492
|
-
```
|
|
493
|
-
|
|
494
|
-
Pi also uses `reserveTokens` to limit the length of its own summary. See the Pi documentation about compaction.
|
|
495
|
-
|
|
496
|
-
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`.
|
|
497
309
|
|
|
498
310
|
## Recipes
|
|
499
311
|
|
|
500
|
-
| I want to... |
|
|
312
|
+
| I want to... | `context-kit.json` |
|
|
501
313
|
| --- | --- |
|
|
502
|
-
| Start
|
|
503
|
-
|
|
|
504
|
-
|
|
|
505
|
-
|
|
|
506
|
-
| Keep more recent tool outputs | `{ "
|
|
507
|
-
| Keep all old file copies | `{ "
|
|
508
|
-
|
|
|
509
|
-
| Turn pi-context-kit off, but keep `recall` | `{ "contextKit": { "enabled": false } }` |
|
|
510
|
-
|
|
511
|
-
To combine recipes, put all the settings in one `contextKit` block:
|
|
512
|
-
|
|
513
|
-
```json
|
|
514
|
-
{
|
|
515
|
-
"contextKit": {
|
|
516
|
-
"thresholdTokens": 150000,
|
|
517
|
-
"methodOrder": ["shake", "handoff", "soft"],
|
|
518
|
-
"prune": { "protectTokens": 80000 }
|
|
519
|
-
}
|
|
520
|
-
}
|
|
521
|
-
```
|
|
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` |
|
|
522
321
|
|
|
523
322
|
## Limits
|
|
524
323
|
|
|
525
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`.
|
|
526
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.
|
|
527
326
|
- **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different.
|
|
528
|
-
- **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.
|
|
529
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.
|
|
530
|
-
-
|
|
531
|
-
- **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.
|
|
532
331
|
|
|
533
|
-
##
|
|
332
|
+
## FAQ
|
|
534
333
|
|
|
535
334
|
**Does it slow down my work?**
|
|
536
335
|
Usually not. The handoff note is written in the background, and pruning and shaking do not use the model.
|