@8monkey/pi-context-history 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Infinite Monkey AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# 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, and folds that summary back into the system prompt — so long-running conversations stay lean, focused, and continuous.
+
+Each feature is independent and can be turned off individually, so you can run the whole pipeline or just the parts you want.
+
+## 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. |
+
+The summary features are a producer/consumer pair: **Generate summary** writes `~/.pi/agent/summary.md`, and **Inject summary** reads it.
+
+## Install
+
+```bash
+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.
+
+Zero runtime dependencies. Pi loads the TypeScript directly, so there's no build step. Runs under Node or Bun.
+
+## Command
+
+| Command | Description |
+|---|---|
+| `/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. |
+
+## Configuration
+
+All configuration is via environment variables.
+
+### Feature toggles
+
+Every feature is **on by default** and switched off by setting its flag to `false` or `0`:
+
+| 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 |
+
+### 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. |
+
+| 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. |
+
+## Development
+
+```bash
+node --test       # run tests
+npm run typecheck
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@8monkey/pi-context-history",
+	"version": "0.1.0",
+	"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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/8monkey-ai/pi-context-history.git"
+	},
+	"homepage": "https://github.com/8monkey-ai/pi-context-history#readme",
+	"bugs": "https://github.com/8monkey-ai/pi-context-history/issues",
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "node --test",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@types/node": "^22",
+		"typescript": "^5"
+	},
+	"keywords": [
+		"pi",
+		"pi-extension",
+		"context",
+		"history",
+		"summary",
+		"tool-calls"
+	]
+}

package/src/build-prompt.ts

@@ -0,0 +1,4 @@
+export function buildContextPrompt(basePrompt: string, summary: string | null, summaryDate: string) {
+	if (!summary) return basePrompt;
+	return `${basePrompt}\n<summary date="${summaryDate}">\n${summary}\n</summary>\n<additional_context>\nThe above is a summary of recent interactions with this contact. Use it to maintain continuity and provide contextual responses.\nContinue the conversation using the same language and tone and follow the language direction above.\n</additional_context>`;
+}

package/src/config.ts

@@ -0,0 +1,8 @@
+// On by default, so the bundle behaves like all four extensions installed; opt out per flag.
+export function featureEnabled(flag: string) {
+	const value = process.env[flag];
+	return value !== "false" && value !== "0";
+}
+
+export const HISTORY_DAYS = Number(process.env["PI_HISTORY_DAYS"]) || 60;
+export const SUMMARY_STALENESS_DAYS = Number(process.env["PI_SUMMARY_STALENESS_DAYS"]) || 3;

package/src/default-prompt.ts

@@ -0,0 +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.
+
+Conversation:
+{conversation_history}`;

package/src/filter.ts

@@ -0,0 +1,3 @@
+export function filterByAge<T extends { timestamp: number }>(messages: T[], now: number, maxAgeMs: number) {
+	return messages.filter((msg) => msg.timestamp >= now - maxAgeMs);
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import { writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } 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,
+	type TranscriptEntry,
+} from "./summary.ts";
+
+const HISTORY_MS = HISTORY_DAYS * 86_400_000;
+const SUMMARY_PATH = join(homedir(), ".pi", "agent", "summary.md");
+
+function registerTrimHistory(pi: ExtensionAPI) {
+	pi.on("context", (event) => {
+		return { messages: filterByAge(event.messages, Date.now(), HISTORY_MS) };
+	});
+}
+
+function registerStripToolHistory(pi: ExtensionAPI) {
+	let boundaryIndex = 0;
+	let newLoopStarted = true;
+
+	pi.on("before_agent_start", () => {
+		newLoopStarted = true;
+	});
+
+	pi.on("context", (event) => {
+		const messages = event.messages as unknown as Message[];
+
+		// Pin the boundary for the whole loop; recomputing per context call would
+		// strip the running turn's own tool exchange mid-flight.
+		if (newLoopStarted) {
+			boundaryIndex = findBoundary(messages);
+			newLoopStarted = false;
+		}
+
+		const cleaned = stripBeforeBoundary(messages, boundaryIndex);
+		return { messages: cleaned as unknown as typeof event.messages };
+	});
+}
+
+function firstUserDate(entries: TranscriptEntry[]) {
+	const first = entries.find((e) => e.type === "message" && e.message?.role === "user");
+	return first ? new Date(first.timestamp) : null;
+}
+
+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);
+	if (!summary) return "empty";
+	writeFileSync(SUMMARY_PATH, summary);
+	return summary;
+}
+
+function registerGenerateSummary(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)) {
+			return;
+		}
+		try {
+			generate(entries);
+		} catch {}
+	});
+
+	pi.registerCommand("summarize-session", {
+		description: "Regenerate the current session's summary now (ignores staleness)",
+		handler: async (_args, ctx: ExtensionCommandContext) => {
+			const entries = ctx.sessionManager.getEntries() as TranscriptEntry[];
+			let result: string | "empty";
+			try {
+				result = generate(entries);
+			} catch (err) {
+				if (ctx.hasUI) ctx.ui.notify(`Failed to generate summary: ${(err as Error).message}.`, "error");
+				return;
+			}
+			if (!ctx.hasUI) return;
+			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");
+			}
+		},
+	});
+}
+
+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 summaryDate = mtime ? (mtime.toISOString().split("T")[0] ?? "unknown") : "unknown";
+
+		const systemPrompt = buildContextPrompt(event.systemPrompt, summary, summaryDate);
+		return { systemPrompt };
+	});
+}
+
+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);
+}

package/src/pi-file.ts

@@ -0,0 +1,26 @@
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_DIR = join(homedir(), ".pi");
+const PROJECT_PI_DIR = join(process.cwd(), ".pi");
+
+// Project `.pi/` wins over `~/.pi/` when both define the same file.
+export function readPiFile(relative: string): string | null {
+	let content: string | null = null;
+	try {
+		content = readFileSync(join(PI_DIR, relative), "utf-8").trim() || null;
+	} catch {}
+	try {
+		content = readFileSync(join(PROJECT_PI_DIR, relative), "utf-8").trim() || null;
+	} catch {}
+	return content;
+}
+
+export function piFileMtime(relative: string): Date | null {
+	try {
+		return statSync(join(PI_DIR, relative)).mtime;
+	} catch {
+		return null;
+	}
+}

package/src/strip.ts

@@ -0,0 +1,44 @@
+// Minimal message shape, to avoid a runtime dependency on the pi package.
+export type Message = {
+	role: string;
+	content: { type: string }[];
+};
+
+// Index of the first message in the current turn: scan from the end, skipping the
+// trailing tool exchange (tool results + the assistant message that called them),
+// so the current turn's tools survive while earlier ones can be stripped.
+export function findBoundary(messages: Message[]) {
+	let boundary = messages.length;
+	while (boundary > 0 && messages[boundary - 1]?.role === "toolResult") {
+		boundary--;
+	}
+	if (boundary > 0) {
+		const prev = messages[boundary - 1];
+		if (prev?.role === "assistant" && prev.content.some((b) => b.type === "toolCall")) {
+			boundary--;
+		}
+	}
+	return boundary;
+}
+
+export function stripBeforeBoundary(messages: Message[], boundaryIndex: number) {
+	const cleaned: Message[] = [];
+	for (let i = 0; i < messages.length; i++) {
+		const msg = messages[i];
+		if (!msg) continue;
+		if (i >= boundaryIndex) {
+			cleaned.push(msg);
+			continue;
+		}
+		if (msg.role === "toolResult") continue;
+		if (msg.role === "assistant") {
+			const hasNonToolContent = msg.content.some((block) => block.type !== "toolCall");
+			if (!hasNonToolContent) continue;
+			const strippedContent = msg.content.filter((block) => block.type !== "toolCall");
+			cleaned.push({ ...msg, content: strippedContent });
+			continue;
+		}
+		cleaned.push(msg);
+	}
+	return cleaned;
+}

package/src/summary.ts

@@ -0,0 +1,64 @@
+import { execFileSync } from "node:child_process";
+import { DEFAULT_SUMMARY_PROMPT } from "./default-prompt.ts";
+
+const DAY_MS = 86_400_000;
+
+export type TranscriptEntry = {
+	type: string;
+	timestamp: string;
+	message?: {
+		role?: string;
+		content?: string | { type: string; text?: string }[];
+	};
+};
+
+export function buildTranscript(entries: TranscriptEntry[]) {
+	return entries
+		.filter((e) => e.type === "message")
+		.map((e) => {
+			const msg = e.message;
+			if (msg?.role !== "user" && msg?.role !== "assistant") return null;
+			const text = Array.isArray(msg.content)
+				? msg.content
+						.filter((b) => b.type === "text")
+						.map((b) => b.text)
+						.join("\n")
+				: String(msg.content || "");
+			if (!text.trim()) return null;
+			const ts = new Date(e.timestamp).toISOString().slice(0, 16).replace("T", " ");
+			return `[${ts}] ${msg.role}: ${text.trim()}`;
+		})
+		.filter(Boolean)
+		.join("\n\n");
+}
+
+function daysSince(date: Date, now: number) {
+	return (now - date.getTime()) / DAY_MS;
+}
+
+export function isStale(summaryMtime: Date | null, firstUserDate: Date | null, now: number, stalenessDays: number) {
+	if (summaryMtime && daysSince(summaryMtime, now) < stalenessDays) return false;
+	if (!firstUserDate || daysSince(firstUserDate, now) < stalenessDays) return false;
+	return true;
+}
+
+export function resolvePromptTemplate(fileContents: string | null) {
+	return fileContents ?? DEFAULT_SUMMARY_PROMPT;
+}
+
+export function runPiSummary(template: string, history: string) {
+	return execFileSync(
+		"pi",
+		[
+			"-p",
+			"--no-session",
+			"--no-extensions",
+			"--no-context-files",
+			"--no-skills",
+			"--system-prompt",
+			template.replace("{conversation_history}", history),
+			"Generate a detailed summary of the conversation. Respond with the summary only. No comments or other text.",
+		],
+		{ encoding: "utf-8", timeout: 60_000 },
+	).trim();
+}