pi-context-kit 0.3.1 → 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 +45 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,42 @@
|
|
|
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. 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
|
+
```
|
|
38
|
+
|
|
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).
|
|
10
40
|
|
|
11
41
|
## Pi alone, and Pi with pi-context-kit
|
|
12
42
|
|
|
@@ -19,24 +49,16 @@ Restart Pi after the install. The defaults work without configuration. Requireme
|
|
|
19
49
|
|
|
20
50
|
The original session entries never change. Only the context that Pi sends to the model becomes smaller.
|
|
21
51
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
## The problem
|
|
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.
|
|
25
53
|
|
|
26
|
-
|
|
27
|
-
Text is measured in **tokens**. One token is approximately 3 to 4 characters of English text.
|
|
54
|
+
## Why long Pi sessions need context management
|
|
28
55
|
|
|
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.
|
|
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.
|
|
32
57
|
|
|
33
|
-
|
|
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.
|
|
34
59
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
3. It leaves the original session entries unchanged. The model can retrieve earlier text on the current branch with `recall`.
|
|
38
|
-
|
|
39
|
-
## Words used in this document
|
|
60
|
+
<details>
|
|
61
|
+
<summary>Words used in this document</summary>
|
|
40
62
|
|
|
41
63
|
| Word | Meaning |
|
|
42
64
|
| --- | --- |
|
|
@@ -50,6 +72,8 @@ pi-context-kit does three things:
|
|
|
50
72
|
| Handoff note | A summary that pi-context-kit writes with the same model as your session. |
|
|
51
73
|
| Pi's summary | The summary that Pi writes when no handoff note is available. |
|
|
52
74
|
|
|
75
|
+
</details>
|
|
76
|
+
|
|
53
77
|
## Install
|
|
54
78
|
|
|
55
79
|
1. Open a terminal.
|
|
@@ -90,30 +114,27 @@ If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: in
|
|
|
90
114
|
|
|
91
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.
|
|
92
116
|
|
|
93
|
-
##
|
|
117
|
+
## How it works during a session
|
|
94
118
|
|
|
95
119
|
```text
|
|
96
120
|
Every turn ends
|
|
97
121
|
|
|
|
98
122
|
v
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
v
|
|
102
|
-
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
|
|
103
124
|
|
|
|
104
125
|
v
|
|
105
126
|
Context above the threshold? --no--> continue to work
|
|
106
127
|
|
|
|
107
128
|
yes
|
|
108
129
|
v
|
|
109
|
-
|
|
130
|
+
Replace old file reads, and prune old tool outputs
|
|
110
131
|
|
|
|
111
132
|
v
|
|
112
133
|
Small enough now? --yes--> continue to work
|
|
113
134
|
|
|
|
114
135
|
no
|
|
115
136
|
v
|
|
116
|
-
|
|
137
|
+
Try each method in "methodOrder": handoff, shake, soft
|
|
117
138
|
```
|
|
118
139
|
|
|
119
140
|
### 1. Old file reads are replaced
|
|
@@ -530,7 +551,7 @@ To combine recipes, put all the settings in one `contextKit` block:
|
|
|
530
551
|
- **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
|
|
531
552
|
- **Subagents** use their own settings. They show no warnings, because they have no screen.
|
|
532
553
|
|
|
533
|
-
##
|
|
554
|
+
## FAQ
|
|
534
555
|
|
|
535
556
|
**Does it slow down my work?**
|
|
536
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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-context-kit",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
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",
|