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.
Files changed (2) hide show
  1. package/README.md +63 -23
  2. package/package.json +10 -4
package/README.md CHANGED
@@ -1,25 +1,64 @@
1
1
  # pi-context-kit
2
2
 
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.
3
+ [![npm version](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) [![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org) [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)
6
4
 
7
- ## The problem
5
+ **Long Pi sessions that stay sharp.**
8
6
 
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.
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
- 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.
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
- pi-context-kit does three things:
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
- 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`.
41
+ ## Pi alone, and Pi with pi-context-kit
21
42
 
22
- ## Words used in this document
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
- ## What happens during a session
117
+ ## How it works during a session
75
118
 
76
119
  ```text
77
120
  Every turn ends
78
121
  |
79
122
  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
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
- 3. Prune old tool outputs
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
- 4. Try each method in "methodOrder": handoff, shake, soft
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. At the threshold, the note is often ready, so compaction is fast.
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
- ## Questions
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.0",
4
- "description": "Context maintenance for Pi: stale read replacement, pruning, handoff compaction with background notes, and recall.",
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
- "handoff"
23
+ "context-window",
24
+ "context-management",
25
+ "coding-agent",
26
+ "llm",
27
+ "handoff",
28
+ "token-optimization"
23
29
  ],
24
30
  "files": [
25
31
  "extensions",