pi-context-kit 0.4.1 → 0.4.3
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 +19 -7
- package/LICENSE +1 -1
- package/README.md +110 -110
- package/context-kit.schema.json +4 -1
- package/extensions/index.ts +87 -157
- package/package.json +37 -45
- package/src/background.ts +2 -3
- package/src/config.ts +12 -41
- package/src/context.ts +43 -16
- package/src/files.ts +6 -13
- package/src/handoff.ts +3 -7
- package/src/maintain.ts +6 -19
- package/src/migrate.ts +6 -18
- package/src/note.ts +5 -6
- package/src/panel.ts +7 -21
- package/src/prune.ts +2 -1
- package/src/recall.ts +14 -37
- package/src/settings-file.ts +7 -20
- package/src/shake.ts +6 -12
- package/src/stale.ts +22 -26
- package/src/status.ts +2 -6
- package/src/tool-calls.ts +2 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,26 +2,38 @@
|
|
|
2
2
|
|
|
3
3
|
Pi shows the entries newer than your installed version after `pi update`.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 0.4.3
|
|
6
|
+
|
|
7
|
+
### Patch Changes
|
|
8
|
+
|
|
9
|
+
- An early summary can no longer be longer than the room left under the threshold. Before, Pi could generate a longer summary that pi-context-kit then rejected.
|
|
10
|
+
- The documentation is in English only. The Simplified Chinese translation is removed.
|
|
11
|
+
- The README states that handoff notes and summaries skip the `context` and `before_provider_request` hooks of other extensions, as Pi's own compaction summaries do.
|
|
12
|
+
|
|
13
|
+
## 0.4.2 - 2026-11-13
|
|
14
|
+
|
|
15
|
+
- Documentation in Simplified Chinese: README, contribution guide and security policy. No change to the extension.
|
|
16
|
+
|
|
17
|
+
## 0.4.1 - 2026-11-13
|
|
6
18
|
|
|
7
19
|
- The README has a quick start and a troubleshooting section. No change to the extension.
|
|
8
20
|
|
|
9
|
-
##
|
|
21
|
+
## 0.4.0 - 2026-11-13
|
|
10
22
|
|
|
11
23
|
- The footer shows how full the context is and when cleanup starts, for example `Context 62% · cleanup at 75%`.
|
|
12
24
|
- `/context-kit` opens a panel to turn cleanup on or off, and to choose when and how to clean up.
|
|
13
25
|
- 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
26
|
- The default threshold is now `75%`. Set `"threshold": "pi"` to wait for Pi's limit as before.
|
|
15
27
|
|
|
16
|
-
##
|
|
28
|
+
## 0.3.2 - 2026-11-11
|
|
17
29
|
|
|
18
30
|
- Documentation only.
|
|
19
31
|
|
|
20
|
-
##
|
|
32
|
+
## 0.3.1 - 2026-11-11
|
|
21
33
|
|
|
22
34
|
- Documentation and package metadata only.
|
|
23
35
|
|
|
24
|
-
##
|
|
36
|
+
## 0.3.0 - 2026-11-11
|
|
25
37
|
|
|
26
38
|
- Breaking: the `staleSuffixTokens` setting is removed. Remove it from your settings.
|
|
27
39
|
- Supports Pi 1.5. Pi 1.0.3 is still the oldest supported version.
|
|
@@ -31,11 +43,11 @@ Pi shows the entries newer than your installed version after `pi update`.
|
|
|
31
43
|
- With Pi's compaction off, pi-context-kit changes the context only on `/compact`.
|
|
32
44
|
- Background handoff notes are cancelled after session-tree navigation.
|
|
33
45
|
|
|
34
|
-
##
|
|
46
|
+
## 0.2.1 - 2026-10-06
|
|
35
47
|
|
|
36
48
|
- The README explains each term, the steps of a session, and each setting.
|
|
37
49
|
|
|
38
|
-
##
|
|
50
|
+
## 0.2.0 - 2026-10-06
|
|
39
51
|
|
|
40
52
|
- Handoff notes use the session's thinking level and tool choice, so Anthropic can reuse the cached conversation.
|
|
41
53
|
- An earlier threshold compacts at the end of a turn, even when no handoff note is ready.
|
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# pi-context-kit: long Pi sessions that stay sharp
|
|
2
2
|
|
|
3
|
-
[](https://github.com/HugoLopes45/pi-extensions/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/pi-context-kit)
|
|
5
5
|
[](https://pi.dev/packages/pi-context-kit)
|
|
6
6
|
[](https://nodejs.org)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
|
|
9
|
-
Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi)
|
|
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.
|
|
10
10
|
|
|
11
|
-
```
|
|
11
|
+
```bash
|
|
12
12
|
pi install npm:pi-context-kit
|
|
13
13
|
```
|
|
14
14
|
|
|
@@ -43,12 +43,12 @@ These notices never change your messages or the model's tool calls. The model's
|
|
|
43
43
|
|
|
44
44
|
## Pi alone, and Pi with pi-context-kit
|
|
45
45
|
|
|
46
|
-
| In a long session
|
|
47
|
-
|
|
|
48
|
-
| The model reads the same file again | Both copies stay in the context.
|
|
49
|
-
| Old tool outputs fill the context
|
|
50
|
-
| The context reaches the limit
|
|
51
|
-
| The model needs a removed detail
|
|
46
|
+
| In a long session | Pi alone | With pi-context-kit |
|
|
47
|
+
| ----------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
|
|
48
|
+
| The model reads the same file again | Both copies stay in the context. | The old copy is replaced, above the threshold. |
|
|
49
|
+
| Old tool outputs fill the context | They stay until Pi summarizes. | They are replaced with a short notice. No model request. |
|
|
50
|
+
| The context reaches the limit | Pi writes a summary. | A handoff note can be ready, because it was written in the background. |
|
|
51
|
+
| The model needs a removed detail | The summary is all that remains in the context. | The model calls `recall` to read the original text. |
|
|
52
52
|
|
|
53
53
|
The original session entries never change. Only the context that Pi sends to the model becomes smaller.
|
|
54
54
|
|
|
@@ -63,17 +63,17 @@ In a long session, the conversation fills the context window. File reads and com
|
|
|
63
63
|
<details>
|
|
64
64
|
<summary>Words used in this document</summary>
|
|
65
65
|
|
|
66
|
-
| Word
|
|
67
|
-
|
|
|
68
|
-
| Token
|
|
69
|
-
| Context window | The maximum number of tokens that the model can read at one time.
|
|
70
|
-
| Context
|
|
71
|
-
| Turn
|
|
72
|
-
| Tool output
|
|
73
|
-
| Threshold
|
|
74
|
-
| Compaction
|
|
75
|
-
| Handoff note
|
|
76
|
-
| Pi's summary
|
|
66
|
+
| Word | Meaning |
|
|
67
|
+
| -------------- | -------------------------------------------------------------------------------------- |
|
|
68
|
+
| Token | A small piece of text. The model counts its memory in tokens. |
|
|
69
|
+
| Context window | The maximum number of tokens that the model can read at one time. |
|
|
70
|
+
| Context | All the text that Pi sends to the model now: instructions, messages, and tool outputs. |
|
|
71
|
+
| Turn | One cycle: the model replies, uses its tools, and stops. |
|
|
72
|
+
| Tool output | The result of a tool, for example the content of a file or the output of a command. |
|
|
73
|
+
| Threshold | The number of tokens at which maintenance starts. |
|
|
74
|
+
| Compaction | Pi replaces the old conversation with a summary. The newest messages stay. |
|
|
75
|
+
| Handoff note | A summary that pi-context-kit writes with the same model as your session. |
|
|
76
|
+
| Pi's summary | The summary that Pi writes when no handoff note is available. |
|
|
77
77
|
|
|
78
78
|
</details>
|
|
79
79
|
|
|
@@ -86,42 +86,34 @@ You need Pi 1.0.3 or later and Node.js 22.19 or later.
|
|
|
86
86
|
3. Look at the footer. It shows `Context 0% · cleanup at 75%` when the extension is active.
|
|
87
87
|
4. Work as usual. Type `/context-kit` to change the settings.
|
|
88
88
|
|
|
89
|
-
##
|
|
90
|
-
|
|
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
|
-
```
|
|
96
|
-
|
|
97
|
-
After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
|
|
98
|
-
|
|
99
|
-
## Use it
|
|
89
|
+
## Footer
|
|
100
90
|
|
|
101
91
|
You do not need to configure anything. pi-context-kit shows its state in Pi's footer:
|
|
102
92
|
|
|
103
|
-
| Footer
|
|
104
|
-
|
|
|
105
|
-
| `Context 62% · cleanup at 75%`
|
|
93
|
+
| Footer | Meaning |
|
|
94
|
+
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
|
|
95
|
+
| `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
|
|
106
96
|
| `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`
|
|
108
|
-
| `Context cleanup off`
|
|
97
|
+
| `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
|
|
98
|
+
| `Context cleanup off` | You turned automatic cleanup off. |
|
|
109
99
|
|
|
110
100
|
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.`
|
|
111
101
|
|
|
102
|
+
## Commands
|
|
103
|
+
|
|
112
104
|
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.
|
|
113
105
|
|
|
114
|
-
| Panel line
|
|
115
|
-
|
|
|
116
|
-
| Automatic cleanup
|
|
117
|
-
| Clean up when the context is | 50% to 90% full, At Pi's limit
|
|
118
|
-
| Cleanup method
|
|
106
|
+
| Panel line | Choices | Setting in the file |
|
|
107
|
+
| ---------------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
|
|
108
|
+
| Automatic cleanup | On, Off | `enabled` |
|
|
109
|
+
| Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` |
|
|
110
|
+
| Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` |
|
|
119
111
|
|
|
120
112
|
The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
|
|
121
113
|
|
|
122
114
|
Outside the interactive mode, `/context-kit` shows the current settings in one line.
|
|
123
115
|
|
|
124
|
-
## How it works
|
|
116
|
+
## How it works
|
|
125
117
|
|
|
126
118
|
```text
|
|
127
119
|
Every turn ends
|
|
@@ -170,14 +162,16 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
|
|
|
170
162
|
|
|
171
163
|
If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other:
|
|
172
164
|
|
|
173
|
-
| Method
|
|
174
|
-
|
|
|
175
|
-
| `handoff` | Replaces the old conversation with the handoff note. The newest messages stay.
|
|
176
|
-
| `shake`
|
|
177
|
-
| `soft`
|
|
165
|
+
| Method | What it does | Uses the model? |
|
|
166
|
+
| --------- | ----------------------------------------------------------------------------------------------------------- | --------------- |
|
|
167
|
+
| `handoff` | Replaces the old conversation with the handoff note. The newest messages stay. | Yes |
|
|
168
|
+
| `shake` | Replaces large old code blocks, XML blocks, and images with a short notice. Your messages are never shaken. | No |
|
|
169
|
+
| `soft` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops here. | Yes |
|
|
178
170
|
|
|
179
171
|
Your work continues during these steps. pi-context-kit never stops a running task to compact.
|
|
180
172
|
|
|
173
|
+
Failed and truncated responses remain under Pi's recovery control. Aborted turns do not start background notes or commit maintenance edits. Disabling cleanup cancels pending notes at the next turn boundary.
|
|
174
|
+
|
|
181
175
|
### The `recall` tool
|
|
182
176
|
|
|
183
177
|
The `recall` tool reads original session text, not the shortened context sent to the model. It can:
|
|
@@ -186,6 +180,8 @@ The `recall` tool reads original session text, not the shortened context sent to
|
|
|
186
180
|
- read an entry's text by ID, with pagination for large entries.
|
|
187
181
|
|
|
188
182
|
Other branches and sessions are excluded. System prompt entries are not searched.
|
|
183
|
+
Shell commands explicitly excluded from model context with `!!` are not available through `recall`.
|
|
184
|
+
|
|
189
185
|
Images remain in the original session entries, but `recall` returns only their MIME types, not image content.
|
|
190
186
|
The model must call `recall` to retrieve a missing detail. Retrieval is not automatic.
|
|
191
187
|
|
|
@@ -206,9 +202,9 @@ This section is for users who edit the settings file. The panel changes the thre
|
|
|
206
202
|
|
|
207
203
|
### The settings files
|
|
208
204
|
|
|
209
|
-
| File
|
|
210
|
-
|
|
|
211
|
-
| `~/.pi/agent/context-kit.json`
|
|
205
|
+
| File | Applies to |
|
|
206
|
+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
207
|
+
| `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. |
|
|
212
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. |
|
|
213
209
|
|
|
214
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.
|
|
@@ -225,21 +221,21 @@ Add the `$schema` line to get completion and checks in editors such as VS Code:
|
|
|
225
221
|
|
|
226
222
|
### Main settings
|
|
227
223
|
|
|
228
|
-
| Setting
|
|
229
|
-
|
|
|
230
|
-
| `enabled`
|
|
231
|
-
| `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"`
|
|
232
|
-
| `strategy`
|
|
224
|
+
| Setting | Allowed values | Default | What it does |
|
|
225
|
+
| ----------- | ----------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------- |
|
|
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. |
|
|
233
229
|
|
|
234
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).
|
|
235
231
|
|
|
236
232
|
**`strategy`.**
|
|
237
233
|
|
|
238
|
-
| Strategy (panel name)
|
|
239
|
-
|
|
|
240
|
-
| `"balanced"` (Summary notes)
|
|
241
|
-
| `"frugal"` (Trim first)
|
|
242
|
-
| `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking.
|
|
234
|
+
| Strategy (panel name) | Above the threshold, after pruning | Background requests |
|
|
235
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
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 |
|
|
243
239
|
|
|
244
240
|
### Advanced settings
|
|
245
241
|
|
|
@@ -258,19 +254,19 @@ Put these settings in an `advanced` block. Most users never need them.
|
|
|
258
254
|
}
|
|
259
255
|
```
|
|
260
256
|
|
|
261
|
-
| Setting
|
|
262
|
-
|
|
|
263
|
-
| `methodOrder`
|
|
264
|
-
| `background`
|
|
265
|
-
| `supersedeReads`
|
|
266
|
-
| `progressRatio`
|
|
267
|
-
| `prune.enabled`
|
|
268
|
-
| `prune.protectTokens`
|
|
269
|
-
| `prune.minSavings`
|
|
270
|
-
| `prune.minTokens`
|
|
271
|
-
| `shake.protectTokens`
|
|
272
|
-
| `shake.minSavings`
|
|
273
|
-
| `shake.blockMinTokens` | `400`
|
|
257
|
+
| Setting | Default | What it does |
|
|
258
|
+
| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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. |
|
|
274
270
|
|
|
275
271
|
### When a setting is incorrect
|
|
276
272
|
|
|
@@ -286,42 +282,42 @@ Pi also warns about a setting name with a spelling mistake, a file that is not v
|
|
|
286
282
|
|
|
287
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.
|
|
288
284
|
|
|
289
|
-
| 0.3 (`contextKit` in `settings.json`)
|
|
290
|
-
|
|
|
291
|
-
| `thresholdTokens: 150000`
|
|
292
|
-
| `thresholdPercent: 75`
|
|
293
|
-
| Both `thresholdTokens` and `thresholdPercent`
|
|
294
|
-
| No threshold (Pi's limit)
|
|
295
|
-
| `methodOrder: ["shake", "handoff", "soft"]`
|
|
296
|
-
| `methodOrder: ["soft"]`
|
|
297
|
-
| Other `methodOrder` values
|
|
298
|
-
| `asyncEnabled`
|
|
299
|
-
| `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced`
|
|
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` |
|
|
300
296
|
|
|
301
297
|
### Pi settings that also apply
|
|
302
298
|
|
|
303
299
|
These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`.
|
|
304
300
|
|
|
305
|
-
| Pi setting
|
|
306
|
-
|
|
|
307
|
-
| `compaction.enabled`
|
|
308
|
-
| `compaction.reserveTokens`
|
|
309
|
-
| `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged.
|
|
310
|
-
| `compaction.modelOverrides`
|
|
301
|
+
| Pi setting | Default | Effect on pi-context-kit |
|
|
302
|
+
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `compaction.enabled` | `true` | `false` stops Pi's automatic compaction. Then pi-context-kit changes the context only on `/compact`, because there is no threshold. |
|
|
304
|
+
| `compaction.reserveTokens` | `16384` | Pi's limit is the context window minus this number. pi-context-kit always starts at this limit or before. |
|
|
305
|
+
| `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
|
|
306
|
+
| `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
|
|
311
307
|
|
|
312
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`.
|
|
313
309
|
|
|
314
|
-
|
|
310
|
+
### Recipes
|
|
315
311
|
|
|
316
|
-
| I want to...
|
|
317
|
-
|
|
|
318
|
-
| Start later, at Pi's own limit
|
|
319
|
-
| Start at the same number of tokens on all models | `{ "threshold": 150000 }`
|
|
320
|
-
| Avoid model requests when possible
|
|
321
|
-
| Never write a handoff note
|
|
322
|
-
| Keep more recent tool outputs
|
|
323
|
-
| Keep all old file copies
|
|
324
|
-
| Turn pi-context-kit off, but keep `recall`
|
|
312
|
+
| I want to... | `context-kit.json` |
|
|
313
|
+
| ------------------------------------------------ | --------------------------------------------------------- |
|
|
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` |
|
|
325
321
|
|
|
326
322
|
## Limits
|
|
327
323
|
|
|
@@ -331,6 +327,7 @@ pi-context-kit has no setting per model. To start earlier for one model only, ma
|
|
|
331
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.
|
|
332
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.
|
|
333
329
|
- **The method order stops at `soft`.** The methods after `soft` do not run.
|
|
330
|
+
- **Summary requests skip session hooks.** Handoff notes and early summaries go to the model directly, as Pi's own compaction summaries do. The `context` and `before_provider_request` hooks of other extensions do not change these requests. If an extension removes sensitive text with these hooks, that text can still reach the model in a summary request.
|
|
334
331
|
- **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.
|
|
335
332
|
|
|
336
333
|
## Troubleshooting
|
|
@@ -363,21 +360,24 @@ Yes. Type `/compact` and the focus, for example `/compact keep the database migr
|
|
|
363
360
|
**The model forgot a detail. What can I do?**
|
|
364
361
|
Ask the model to use the `recall` tool, for example: "Use recall to find the error message from the first test run."
|
|
365
362
|
|
|
366
|
-
##
|
|
363
|
+
## Update, try or remove
|
|
367
364
|
|
|
368
|
-
```
|
|
369
|
-
npm
|
|
370
|
-
npm
|
|
365
|
+
```bash
|
|
366
|
+
pi update npm:pi-context-kit # update, then restart Pi
|
|
367
|
+
pi -e npm:pi-context-kit # try for one session without installing
|
|
368
|
+
pi remove npm:pi-context-kit # remove, then restart Pi
|
|
371
369
|
```
|
|
372
370
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
371
|
+
After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
|
|
372
|
+
|
|
373
|
+
## Contributing
|
|
374
|
+
|
|
375
|
+
See [CONTRIBUTING.md](https://github.com/HugoLopes45/pi-extensions/blob/main/CONTRIBUTING.md) for setup, checks and releases. Report bugs on [GitHub Issues](https://github.com/HugoLopes45/pi-extensions/issues), and vulnerabilities through [SECURITY.md](https://github.com/HugoLopes45/pi-extensions/blob/main/SECURITY.md).
|
|
376
376
|
|
|
377
|
-
##
|
|
377
|
+
## Author
|
|
378
378
|
|
|
379
|
-
|
|
379
|
+
Built by [Hugo Lopes](https://github.com/HugoLopes45), a senior frontend developer based in Paris, passionate about AI and agent harnesses.
|
|
380
380
|
|
|
381
381
|
## License
|
|
382
382
|
|
|
383
|
-
MIT
|
|
383
|
+
[MIT](LICENSE)
|
package/context-kit.schema.json
CHANGED
|
@@ -17,7 +17,10 @@
|
|
|
17
17
|
"default": "75%",
|
|
18
18
|
"oneOf": [
|
|
19
19
|
{ "type": "integer", "minimum": 1 },
|
|
20
|
-
{
|
|
20
|
+
{
|
|
21
|
+
"type": "string",
|
|
22
|
+
"pattern": "^(0*100(\\.0+)?|0*[1-9]\\d?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*)%$"
|
|
23
|
+
},
|
|
21
24
|
{ "const": "pi" }
|
|
22
25
|
]
|
|
23
26
|
},
|