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.
Files changed (2) hide show
  1. package/README.md +45 -24
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,12 +1,42 @@
1
1
  # pi-context-kit
2
2
 
3
- Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). It keeps the context of long Pi sessions small: pi-context-kit removes old file copies and old tool outputs from the model's context, and prepares the summary before Pi needs it. The session keeps the original text, and the model can read it again with `recall`.
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)
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 after the install. The defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
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
- This extension is for Pi users with long 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` uses a handoff note instead of Pi's summary.
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
- An AI model can read only a limited amount of text at one time. This limit is the **context window**.
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
- In a long session, the conversation fills the context window. File reads and command outputs are usually the largest parts.
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
- pi-context-kit does three things:
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
- 1. It replaces repeated file reads and old tool outputs in the model's context.
36
- 2. When a summary is necessary, it can prepare a handoff note in advance.
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
- ## What happens during a session
117
+ ## How it works during a session
94
118
 
95
119
  ```text
96
120
  Every turn ends
97
121
  |
98
122
  v
99
- 1. Remove old file reads that a newer read replaced
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
- 3. Prune old tool outputs
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
- 4. Try each method in "methodOrder": handoff, shake, soft
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
- ## Questions
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.1",
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",