pi-context-kit 0.3.0 → 0.3.2
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 +63 -23
- package/package.json +10 -4
package/README.md
CHANGED
|
@@ -1,25 +1,64 @@
|
|
|
1
1
|
# pi-context-kit
|
|
2
2
|
|
|
3
|
-
pi-context-kit
|
|
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.
|
|
3
|
+
[](https://www.npmjs.com/package/pi-context-kit) [](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [](https://nodejs.org) [](LICENSE)
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
**Long Pi sessions that stay sharp.**
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
Text is measured in **tokens**. One token is approximately 3 to 4 characters of English text.
|
|
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.
|
|
11
8
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
9
|
+
```sh
|
|
10
|
+
pi install npm:pi-context-kit
|
|
11
|
+
```
|
|
12
|
+
|
|
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. Tune it later if you want.
|
|
23
|
+
|
|
24
|
+
## What the model sees
|
|
25
|
+
|
|
26
|
+
Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`methodOrder`](#methodorder)):
|
|
27
|
+
|
|
28
|
+
```diff
|
|
29
|
+
- <first read of src/app.ts, about 5,000 tokens>
|
|
30
|
+
+ [Superseded by a newer read of this file]
|
|
31
|
+
|
|
32
|
+
- <output of npm test from one hour ago, about 12,000 tokens>
|
|
33
|
+
+ [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.]
|
|
34
|
+
|
|
35
|
+
- <a large code block in an old reply, about 2,000 tokens>
|
|
36
|
+
+ [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.]
|
|
37
|
+
```
|
|
15
38
|
|
|
16
|
-
|
|
39
|
+
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).
|
|
17
40
|
|
|
18
|
-
|
|
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`.
|
|
41
|
+
## Pi alone, and Pi with pi-context-kit
|
|
21
42
|
|
|
22
|
-
|
|
43
|
+
| In a long session | Pi alone | With pi-context-kit |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| The model reads the same file again | Both copies stay in the context. | The old copy is replaced, above the threshold. |
|
|
46
|
+
| Old tool outputs fill the context | They stay until Pi summarizes. | They are replaced with a short notice. No model request. |
|
|
47
|
+
| The context reaches the limit | Pi writes a summary. | A handoff note can be ready, because it was written in the background. |
|
|
48
|
+
| The model needs a removed detail | The summary is all that remains in the context. | The model calls `recall` to read the original text. |
|
|
49
|
+
|
|
50
|
+
The original session entries never change. Only the context that Pi sends to the model becomes smaller.
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
## Why long Pi sessions need context management
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
<details>
|
|
61
|
+
<summary>Words used in this document</summary>
|
|
23
62
|
|
|
24
63
|
| Word | Meaning |
|
|
25
64
|
| --- | --- |
|
|
@@ -33,6 +72,8 @@ pi-context-kit does three things:
|
|
|
33
72
|
| Handoff note | A summary that pi-context-kit writes with the same model as your session. |
|
|
34
73
|
| Pi's summary | The summary that Pi writes when no handoff note is available. |
|
|
35
74
|
|
|
75
|
+
</details>
|
|
76
|
+
|
|
36
77
|
## Install
|
|
37
78
|
|
|
38
79
|
1. Open a terminal.
|
|
@@ -46,6 +87,8 @@ pi-context-kit does three things:
|
|
|
46
87
|
|
|
47
88
|
To check the installation, type `pi list`. The list must show `npm:pi-context-kit`.
|
|
48
89
|
|
|
90
|
+
To update, type `pi update npm:pi-context-kit` and restart Pi.
|
|
91
|
+
|
|
49
92
|
To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
|
|
50
93
|
|
|
51
94
|
## Recommended setup
|
|
@@ -71,30 +114,27 @@ If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: in
|
|
|
71
114
|
|
|
72
115
|
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
116
|
|
|
74
|
-
##
|
|
117
|
+
## How it works during a session
|
|
75
118
|
|
|
76
119
|
```text
|
|
77
120
|
Every turn ends
|
|
78
121
|
|
|
|
79
122
|
v
|
|
80
|
-
|
|
81
|
-
|
|
|
82
|
-
v
|
|
83
|
-
Context near the threshold? --yes--> 2. Start a handoff note in the background
|
|
123
|
+
Context near the threshold? --yes--> Start a handoff note in the background
|
|
84
124
|
|
|
|
85
125
|
v
|
|
86
126
|
Context above the threshold? --no--> continue to work
|
|
87
127
|
|
|
|
88
128
|
yes
|
|
89
129
|
v
|
|
90
|
-
|
|
130
|
+
Replace old file reads, and prune old tool outputs
|
|
91
131
|
|
|
|
92
132
|
v
|
|
93
133
|
Small enough now? --yes--> continue to work
|
|
94
134
|
|
|
|
95
135
|
no
|
|
96
136
|
v
|
|
97
|
-
|
|
137
|
+
Try each method in "methodOrder": handoff, shake, soft
|
|
98
138
|
```
|
|
99
139
|
|
|
100
140
|
### 1. Old file reads are replaced
|
|
@@ -331,7 +371,7 @@ Example: try shaking first, because it does not call the model.
|
|
|
331
371
|
|
|
332
372
|
Prepares the handoff note in the background, before the threshold.
|
|
333
373
|
|
|
334
|
-
- `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens.
|
|
374
|
+
- `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. If the note is ready at the threshold, compaction is fast.
|
|
335
375
|
- `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
|
|
336
376
|
|
|
337
377
|
This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`.
|
|
@@ -511,7 +551,7 @@ To combine recipes, put all the settings in one `contextKit` block:
|
|
|
511
551
|
- **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
|
|
512
552
|
- **Subagents** use their own settings. They show no warnings, because they have no screen.
|
|
513
553
|
|
|
514
|
-
##
|
|
554
|
+
## FAQ
|
|
515
555
|
|
|
516
556
|
**Does it slow down my work?**
|
|
517
557
|
Usually not. The handoff note is written in the background, and pruning and shaking do not use the model.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-context-kit",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.3.2",
|
|
4
|
+
"description": "Pi compaction and context management for the Pi coding agent: replace stale file reads, prune old tool outputs, prepare handoff notes in the background, and recall the original text.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "HugoLopes45 (https://github.com/HugoLopes45)",
|
|
@@ -15,11 +15,17 @@
|
|
|
15
15
|
},
|
|
16
16
|
"keywords": [
|
|
17
17
|
"pi-package",
|
|
18
|
-
"pi-extension",
|
|
19
18
|
"pi",
|
|
19
|
+
"pi-extension",
|
|
20
|
+
"pi-coding-agent",
|
|
20
21
|
"compaction",
|
|
21
22
|
"context",
|
|
22
|
-
"
|
|
23
|
+
"context-window",
|
|
24
|
+
"context-management",
|
|
25
|
+
"coding-agent",
|
|
26
|
+
"llm",
|
|
27
|
+
"handoff",
|
|
28
|
+
"token-optimization"
|
|
23
29
|
],
|
|
24
30
|
"files": [
|
|
25
31
|
"extensions",
|