@8monkey/pi-context-history 0.2.0 → 0.2.1

package/README.md

@@ -1,20 +1,10 @@
 # pi-context-history
 
-A [Pi](https://github.com/earendil-works/pi-coding-agent) extension that manages conversation context end-to-end. It trims old history, strips stale tool chatter from earlier turns, keeps a rolling session summary, folds that summary back into the system prompt, and lets you append messages to the history by hand — so long-running conversations stay lean, focused, and continuous.
+A [Pi](https://github.com/earendil-works/pi-coding-agent) extension that keeps long-running conversations lean and focused.
 
-Each feature is independent and can be turned off individually, so you can run the whole pipeline or just the parts you want.
+In long sessions, the context window fills with old messages and tool output the model no longer needs. This extension removes what's stale and keeps a rolling summary so earlier context isn't lost.
 
-## Features
-
-| Feature | Hook | What it does |
-|---|---|---|
-| **Trim history** | `context` | Drops messages older than a configurable age from the context. |
-| **Strip tool history** | `context` | Removes tool calls and results from prior turns, keeping the current turn's tool interactions intact. |
-| **Generate summary** | `session_start` | Regenerates a stale rolling summary in the background when a session resumes; also available on demand via `/summarize-session`. |
-| **Inject summary** | `before_agent_start` | Folds the rolling summary into the system prompt so the model continues with prior context. |
-| **Append message** | command | Adds a user or assistant message to the end of the history via `/add-user-message` and `/add-assistant-message`. |
-
-The summary features are a producer/consumer pair: **Generate summary** writes `~/.pi/agent/summary.md`, and **Inject summary** reads it.
+Everything is on by default and works once installed. Each feature can be disabled independently.
 
 ## Install
 
@@ -22,55 +12,55 @@ The summary features are a producer/consumer pair: **Generate summary** writes `
 pi install npm:@8monkey/pi-context-history
 ```
 
-## How it works
-
-- **Trim history.** On each `context` event the message list is filtered to those whose `timestamp` is within `PI_HISTORY_DAYS`. Messages exactly at the cutoff are kept.
-- **Strip tool history.** Tool calls and results from earlier turns are removed; the current turn is left untouched. At the start of each agent loop the extension marks where the current turn begins (scanning back past the latest tool exchange) and holds that mark steady across the loop, so a running turn is never stripped mid-flight. Before the mark, tool results are dropped and assistant messages lose their tool-call blocks (if nothing else remains, the message goes too).
-- **Generate summary.** When you resume a session whose summary has gone stale — older than `PI_SUMMARY_STALENESS_DAYS`, with a first message older than the window too — the extension rebuilds `~/.pi/agent/summary.md` by shelling out to `pi -p` (extensions, context files, and skills disabled). New and empty sessions are skipped. To override the built-in prompt, drop your own at `prompts/session-summary.md` (project `.pi/` wins over `~/.pi/`); it must contain the `{conversation_history}` placeholder.
-- **Inject summary.** Before each agent run, when `~/.pi/agent/summary.md` exists, its contents are wrapped in a `<summary date="…">` block (the date is the file's modified time) followed by an `<additional_context>` note telling the model to maintain continuity and match the existing language and tone.
-- **Append message.** `/add-user-message <text>` and `/add-assistant-message <text>` write a message with the matching role to the end of the session history. The entry is persisted immediately but enters the live context on the next rebuild (resume or branch), since Pi has no public way to inject into a running turn. Appending an assistant message requires a model to be selected, as the message records its identity.
+## Features
 
-Zero runtime dependencies. Pi loads the TypeScript directly, so there's no build step. Runs under Node or Bun.
+- **Trim history.** Drops messages older than `PI_HISTORY_DAYS` (60 by default) on each context rebuild.
+- **Strip tool history.** Removes tool calls and results from turns before the current one, leaving the in-progress turn untouched.
+- **Compact.** Keeps a rolling summary of your sessions in `~/.pi/agent/compact.md` and folds it into the system prompt, so the model continues with prior context. The summary regenerates during session start when you resume a session after it has gone stale. Run `/compact-session` to regenerate on demand.
+- **Append message.** Adds a user or assistant message to the end of the history with `/add-user-message` and `/add-assistant-message`.
 
 ## Commands
 
-| Command | Description |
+| Command | What it does |
 |---|---|
-| `/add-assistant-message <text>` | Append an assistant message to the end of the history. Persisted immediately; enters context on the next rebuild. Available only when the **Append message** feature is enabled. |
-| `/add-user-message <text>` | Append a user message to the end of the history. Persisted immediately; enters context on the next rebuild. Available only when the **Append message** feature is enabled. |
-| `/summarize-session` | Regenerate the current session's summary on demand, ignoring the staleness window. Writes `~/.pi/agent/summary.md` and reports success, failure, or an empty session. Available only when the **Generate summary** feature is enabled. |
+| `/compact-session` | Write a fresh summary of the current session now, ignoring the staleness window. |
+| `/add-user-message <text>` | Add a message to the conversation as if you had typed it. |
+| `/add-assistant-message <text>` | Add a message as if the assistant had said it. Requires a selected model. |
+
+Appended messages are persisted immediately but only enter the live context on the next rebuild (resume or branch).
 
 ## Configuration
 
-All configuration is via environment variables.
+All configuration is via environment variables, and all of it is optional.
 
 ### Feature toggles
 
-Every feature is **on by default** and switched off by setting its flag to `false` or `0`:
+Each feature is on by default. Set its variable to `false` to disable it.
 
-| Variable | Default | Feature |
-|---|---|---|
-| `PI_TRIM_HISTORY` | on | Trim history |
-| `PI_STRIP_TOOL_HISTORY` | on | Strip tool history |
-| `PI_GENERATE_SUMMARY` | on | Generate summary |
-| `PI_INJECT_SUMMARY` | on | Inject summary |
-| `PI_APPEND_MESSAGE` | on | Append message |
+| Variable | Feature |
+|---|---|
+| `PI_TRIM_HISTORY` | Trim history |
+| `PI_STRIP_TOOL_HISTORY` | Strip tool history |
+| `PI_COMPACT` | Compact (generation and injection) |
+| `PI_APPEND_MESSAGE` | The append-message commands |
 
 ### Settings
 
 | Variable | Default | Description |
 |---|---|---|
-| `PI_HISTORY_DAYS` | `60` | Maximum age, in days, of messages kept in the context. |
-| `PI_SUMMARY_STALENESS_DAYS` | `3` | How many days old a summary (and the session's first message) must be before automatic regeneration kicks in on session start. |
+| `PI_HISTORY_DAYS` | `60` | Maximum age, in days, of messages kept in context. |
+| `PI_COMPACT_STALENESS_DAYS` | `3` | How old the summary may get before it's regenerated on resume. |
 
-| File | Default | Description |
-|---|---|---|
-| `prompts/session-summary.md` | built-in default | Optional override for the summary prompt. Read from project `.pi/` first, then `~/.pi/`. Must contain the `{conversation_history}` placeholder. |
+### Compact prompt
+
+Override the built-in prompt with a file at `prompts/compact.md`, read from the project `.pi/` first, then `~/.pi/`. It must contain the `{conversation_history}` placeholder.
 
 ## Development
 
+No runtime dependencies. Pi loads the TypeScript directly, so there's no build step, and it runs under Node or Bun.
+
 ```bash
-node --test       # run tests
+node --test        # run tests
 npm run typecheck
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@8monkey/pi-context-history",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Pi extension that manages conversation context: trims old history, strips stale tool calls, and keeps a rolling summary fed back into the system prompt. Each feature toggles independently.",
 	"license": "MIT",
 	"type": "module",

package/src/{summary.ts → compact.ts}

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { DEFAULT_SUMMARY_PROMPT } from "./default-prompt.ts";
+import { DEFAULT_COMPACT_PROMPT } from "./default-prompt.ts";
 
 const DAY_MS = 86_400_000;
 
@@ -43,10 +43,10 @@ export function isStale(summaryMtime: Date | null, firstUserDate: Date | null, n
 }
 
 export function resolvePromptTemplate(fileContents: string | null) {
-	return fileContents ?? DEFAULT_SUMMARY_PROMPT;
+	return fileContents ?? DEFAULT_COMPACT_PROMPT;
 }
 
-export function runPiSummary(template: string, history: string) {
+export function runPiCompact(template: string, history: string) {
 	return execFileSync(
 		"pi",
 		[

package/src/config.ts

@@ -5,4 +5,4 @@ export function featureEnabled(flag: string) {
 }
 
 export const HISTORY_DAYS = Number(process.env["PI_HISTORY_DAYS"]) || 60;
-export const SUMMARY_STALENESS_DAYS = Number(process.env["PI_SUMMARY_STALENESS_DAYS"]) || 3;
+export const COMPACT_STALENESS_DAYS = Number(process.env["PI_COMPACT_STALENESS_DAYS"]) || 3;

package/src/default-prompt.ts

@@ -1,4 +1,4 @@
-export const DEFAULT_SUMMARY_PROMPT = `You are summarizing a conversation so it can be continued later. Produce a concise, structured summary capturing the main topics, decisions, open questions, and any important context. Be factual and neutral.
+export const DEFAULT_COMPACT_PROMPT = `You are summarizing a conversation so it can be continued later. Produce a concise, structured summary capturing the main topics, decisions, open questions, and any important context. Be factual and neutral.
 
 Conversation:
 {conversation_history}`;

package/src/index.ts

@@ -3,20 +3,21 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, SessionManager } from "@earendil-works/pi-coding-agent";
 import { buildContextPrompt } from "./build-prompt.ts";
-import { featureEnabled, HISTORY_DAYS, SUMMARY_STALENESS_DAYS } from "./config.ts";
-import { filterByAge } from "./filter.ts";
-import { piFileMtime, readPiFile } from "./pi-file.ts";
-import { findBoundary, stripBeforeBoundary, type Message } from "./strip.ts";
 import {
 	buildTranscript,
 	isStale,
 	resolvePromptTemplate,
-	runPiSummary,
+	runPiCompact,
 	type TranscriptEntry,
-} from "./summary.ts";
+} from "./compact.ts";
+import { COMPACT_STALENESS_DAYS, featureEnabled, HISTORY_DAYS } from "./config.ts";
+import { filterByAge } from "./filter.ts";
+import { piFileMtime, readPiFile } from "./pi-file.ts";
+import { findBoundary, stripBeforeBoundary, type Message } from "./strip.ts";
 
 const HISTORY_MS = HISTORY_DAYS * 86_400_000;
-const SUMMARY_PATH = join(homedir(), ".pi", "agent", "summary.md");
+const COMPACT_RELATIVE_PATH = "agent/compact.md";
+const COMPACT_PATH = join(homedir(), ".pi", COMPACT_RELATIVE_PATH);
 const ZERO_USAGE = {
 	input: 0,
 	output: 0,
@@ -63,18 +64,18 @@ function firstUserDate(entries: TranscriptEntry[]) {
 function generate(entries: TranscriptEntry[]): string | "empty" {
 	const history = buildTranscript(entries);
 	if (!history) return "empty";
-	const template = resolvePromptTemplate(readPiFile("prompts/session-summary.md"));
-	const summary = runPiSummary(template, history);
+	const template = resolvePromptTemplate(readPiFile("prompts/compact.md"));
+	const summary = runPiCompact(template, history);
 	if (!summary) return "empty";
-	writeFileSync(SUMMARY_PATH, summary);
+	writeFileSync(COMPACT_PATH, summary);
 	return summary;
 }
 
-function registerGenerateSummary(pi: ExtensionAPI) {
+function registerCompact(pi: ExtensionAPI) {
 	pi.on("session_start", (event, ctx) => {
 		if (event.reason === "new") return;
 		const entries = ctx.sessionManager.getEntries() as TranscriptEntry[];
-		if (!isStale(piFileMtime("agent/summary.md"), firstUserDate(entries), Date.now(), SUMMARY_STALENESS_DAYS)) {
+		if (!isStale(piFileMtime(COMPACT_RELATIVE_PATH), firstUserDate(entries), Date.now(), COMPACT_STALENESS_DAYS)) {
 			return;
 		}
 		try {
@@ -82,8 +83,8 @@ function registerGenerateSummary(pi: ExtensionAPI) {
 		} catch {}
 	});
 
-	pi.registerCommand("summarize-session", {
-		description: "Regenerate the current session's summary now (ignores staleness)",
+	pi.registerCommand("compact-session", {
+		description: "Regenerate the session summary in ~/.pi/agent/compact.md now (ignores staleness)",
 		handler: async (_args, ctx) => {
 			const entries = ctx.sessionManager.getEntries() as TranscriptEntry[];
 			let result: string | "empty";
@@ -97,16 +98,14 @@ function registerGenerateSummary(pi: ExtensionAPI) {
 			if (result === "empty") {
 				ctx.ui.notify("Nothing to summarize in this session.", "info");
 			} else {
-				ctx.ui.notify("Session summary written to ~/.pi/agent/summary.md.", "info");
+				ctx.ui.notify("Session summary written to ~/.pi/agent/compact.md.", "info");
 			}
 		},
 	});
-}
 
-function registerInjectSummary(pi: ExtensionAPI) {
 	pi.on("before_agent_start", (event) => {
-		const summary = readPiFile("agent/summary.md");
-		const mtime = summary ? piFileMtime("agent/summary.md") : null;
+		const summary = readPiFile(COMPACT_RELATIVE_PATH);
+		const mtime = summary ? piFileMtime(COMPACT_RELATIVE_PATH) : null;
 		const summaryDate = mtime ? (mtime.toISOString().split("T")[0] ?? "unknown") : "unknown";
 
 		const systemPrompt = buildContextPrompt(event.systemPrompt, summary, summaryDate);
@@ -163,7 +162,6 @@ function registerAppendMessage(pi: ExtensionAPI) {
 export default function (pi: ExtensionAPI) {
 	if (featureEnabled("PI_TRIM_HISTORY")) registerTrimHistory(pi);
 	if (featureEnabled("PI_STRIP_TOOL_HISTORY")) registerStripToolHistory(pi);
-	if (featureEnabled("PI_GENERATE_SUMMARY")) registerGenerateSummary(pi);
-	if (featureEnabled("PI_INJECT_SUMMARY")) registerInjectSummary(pi);
+	if (featureEnabled("PI_COMPACT")) registerCompact(pi);
 	if (featureEnabled("PI_APPEND_MESSAGE")) registerAppendMessage(pi);
 }