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