pi-mem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Bashi
+
+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,138 @@
+# pi-mem
+
+Persistent memory extension for [pi](https://github.com/badlogic/pi-mono). Automatically captures what pi does during sessions, compresses observations into searchable memories, and injects relevant context into future sessions.
+
+## Features
+
+- **Automatic observation capture** — hooks into `tool_result` events to record tool executions
+- **LLM-powered observation extraction** — extracts structured facts, narrative, concepts, and file references from tool output
+- **Session summaries** — compresses observations into searchable memories using checkpoint summarization
+- **Vector + full-text search** — LanceDB-backed semantic and keyword search across all memories
+- **Context injection** — automatically loads relevant past memories at session start
+- **Memory tools** — `search`, `timeline`, `get_observations`, and `save_memory` tools for the LLM
+- **Privacy controls** — `<private>` tags to exclude sensitive content
+- **Project awareness** — scopes memories per project (from git remote), supports cross-project search
+
+## Installation
+
+```bash
+pi install npm:pi-mem
+```
+
+Or to try without installing:
+
+```bash
+pi -e npm:pi-mem
+```
+
+## Configuration
+
+Create `~/.pi/agent/pi-mem.json` or `~/.pi-mem/config.json` (optional — all settings have sensible defaults):
+
+```json
+{
+  "enabled": true,
+  "autoInject": true,
+  "maxObservationLength": 4000,
+  "summaryModel": "anthropic/claude-haiku-3",
+  "indexSize": 10,
+  "tokenBudget": 2000,
+  "embeddingProvider": "openai",
+  "embeddingModel": "text-embedding-3-small",
+  "embeddingDims": 1536
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable/disable the extension |
+| `autoInject` | `true` | Automatically inject past memories at session start |
+| `maxObservationLength` | `4000` | Max characters per tool output observation |
+| `summaryModel` | (current model) | Model to use for session summarization |
+| `observerModel` | (falls back to summaryModel) | Model for per-tool observation extraction |
+| `thinkingLevel` | (current level) | Thinking level for LLM calls |
+| `indexSize` | `10` | Max entries in the project memory index |
+| `tokenBudget` | `2000` | Max tokens for injected context |
+| `embeddingProvider` | (none) | Pi provider name for embeddings. Must support OpenAI-compatible `/v1/embeddings` |
+| `embeddingModel` | `text-embedding-3-small` | Embedding model name |
+| `embeddingDims` | `1536` | Embedding vector dimensions (must match the model) |
+
+### Embedding Setup
+
+For vector/semantic search, configure an embedding provider. The provider must support the OpenAI-compatible `/v1/embeddings` endpoint. Add the provider name from your `~/.pi/agent/models.json`:
+
+```json
+{
+  "embeddingProvider": "openai",
+  "embeddingModel": "text-embedding-3-small",
+  "embeddingDims": 1536
+}
+```
+
+Without an embedding provider, full-text search still works.
+
+## Data Storage
+
+All data is stored in `~/.pi-mem/`:
+
+```
+~/.pi-mem/
+├── lancedb/                      # Observation store (LanceDB)
+└── config.json                   # User preferences (optional)
+```
+
+## Commands
+
+- `/mem` — Show current memory status (project, observation count, vector DB status)
+
+## Tools (available to the LLM)
+
+### search
+
+Search past observations and summaries with full-text search:
+
+```
+search({ query: "authentication flow" })
+search({ query: "authentication", project: "my-app", limit: 5 })
+```
+
+### timeline
+
+Get chronological context around a specific observation:
+
+```
+timeline({ anchor: "abc12345" })
+timeline({ query: "auth bug", depth_before: 5, depth_after: 5 })
+```
+
+### get_observations
+
+Fetch full details for specific observation IDs:
+
+```
+get_observations({ ids: ["abc12345", "def67890"] })
+```
+
+### save_memory
+
+Explicitly save important information:
+
+```
+save_memory({
+  text: "Decided to use PostgreSQL for ACID transactions",
+  title: "Database choice",
+  concepts: ["decision", "architecture"]
+})
+```
+
+## Privacy
+
+Wrap sensitive content in `<private>` tags in tool output — it will be stripped before observation:
+
+```
+API key is <private>sk-abc123</private>
+```
+
+## License
+
+MIT

package/compression-agent.ts

@@ -0,0 +1,292 @@
+/**
+ * Compression agent for pi-mem.
+ * Spawns a headless pi sub-agent to compress observations into structured summaries.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { PiMemConfig } from "./config.js";
+
+/** Observation shape as passed from index.ts to the summarizer */
+export interface Observation {
+	timestamp: string;
+	toolName: string;
+	input: Record<string, unknown>;
+	output: string;
+	cwd: string;
+}
+
+const DEBUG_LOG_PATH = path.join(os.homedir(), ".pi-mem", "debug-summarize.log");
+
+function debugLog(msg: string) {
+	try { fs.appendFileSync(DEBUG_LOG_PATH, `[${new Date().toISOString()}] ${msg}\n`); } catch {}
+}
+
+export interface SessionSummary {
+	request: string;
+	investigated: string;
+	learned: string;
+	completed: string;
+	nextSteps: string;
+	filesRead: string[];
+	filesModified: string[];
+	concepts: string[];
+}
+
+export interface SummarizeContext {
+	/** Current session model */
+	model: any;
+	/** Current session thinking level */
+	thinkingLevel: string;
+	/** Pre-collected file paths (overrides LLM extraction) */
+	filesRead?: string[];
+	/** Pre-collected file paths (overrides LLM extraction) */
+	filesModified?: string[];
+}
+
+function killProcess(proc: ChildProcess): void {
+	try { proc.kill("SIGTERM"); } catch {}
+	setTimeout(() => { try { proc.kill("SIGKILL"); } catch {} }, 2000);
+}
+
+/**
+ * Run a pi sub-agent and return the response text.
+ */
+function runSubAgent(
+	prompt: string,
+	systemPrompt: string,
+	model: string,
+	thinkingLevel: string,
+): Promise<{ ok: true; response: string } | { ok: false; error: string }> {
+	return new Promise((resolve) => {
+		const proc = spawn("pi", [
+			"--mode", "json",
+			"-p",
+			"--no-session",
+			"--no-tools",
+			"--system-prompt", systemPrompt,
+			"--model", model,
+			"--thinking", thinkingLevel,
+			prompt,
+		], {
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env, PI_MEM_SUB_AGENT: "1" },
+		});
+
+		let buffer = "";
+		let lastAssistantText = "";
+		let stderr = "";
+
+		const timeout = setTimeout(() => {
+			killProcess(proc);
+			resolve({ ok: false, error: "Summarization timeout (30s)" });
+		}, 30_000);
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			try {
+				const event = JSON.parse(line);
+				if (event.type === "message_end" && event.message?.role === "assistant") {
+					for (const part of event.message.content) {
+						if (part.type === "text") {
+							lastAssistantText = part.text;
+						}
+					}
+				}
+			} catch {
+				// ignore non-JSON lines
+			}
+		};
+
+		proc.stdout!.on("data", (data: Buffer) => {
+			buffer += data.toString();
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) processLine(line);
+		});
+
+		proc.stderr!.on("data", (data: Buffer) => {
+			stderr += data.toString();
+		});
+
+		proc.on("close", (code) => {
+			clearTimeout(timeout);
+			if (buffer.trim()) processLine(buffer);
+
+			if (lastAssistantText) {
+				resolve({ ok: true, response: lastAssistantText });
+			} else if (code !== 0) {
+				resolve({ ok: false, error: `Sub-agent failed (exit ${code}): ${stderr.trim().slice(0, 500) || "(no output)"}` });
+			} else {
+				resolve({ ok: false, error: "Sub-agent returned no response" });
+			}
+		});
+
+		proc.on("error", (err) => {
+			clearTimeout(timeout);
+			resolve({ ok: false, error: `Failed to spawn pi: ${err.message}` });
+		});
+	});
+}
+
+/**
+ * Summarize observations using an LLM compression agent.
+ * Falls back to raw observation extraction on failure.
+ */
+export async function summarize(
+	observations: Observation[],
+	config: PiMemConfig,
+	context: SummarizeContext,
+): Promise<SessionSummary> {
+	// Resolve model: config override → current session model
+	const model = config.summaryModel
+		|| (context.model ? `${context.model.provider}/${context.model.id}` : undefined);
+
+	// Resolve thinking level: config override → current session thinking level
+	const thinkingLevel = config.thinkingLevel || context.thinkingLevel || "medium";
+
+	if (!model) {
+		debugLog("No model available, using fallback");
+		const summary = extractFallbackSummary(observations);
+		// Override with pre-collected files even for fallback
+		if (context.filesRead) summary.filesRead = context.filesRead;
+		if (context.filesModified) summary.filesModified = context.filesModified;
+		return summary;
+	}
+
+	// Format observations into prompt — use structured titles and narratives
+	// (already LLM-compressed by observer agent, no need to truncate)
+	const obsText = observations.map((obs, i) => {
+		return `### Observation ${i + 1}: ${obs.toolName} [${obs.timestamp}]
+Title: ${JSON.stringify(obs.input).includes("summary") ? (obs.input as any).summary : obs.toolName}
+Content: ${obs.output}`;
+	}).join("\n\n");
+
+	const prompt = `Compress the following coding session observations into a structured summary.
+
+${obsText}
+
+Respond with a structured markdown summary using EXACTLY these section headers:
+## Request
+## What Was Investigated
+## What Was Learned
+## What Was Completed
+## Next Steps
+## Files
+## Concepts`;
+
+	debugLog(`--- Starting summarization (${observations.length} obs, model: ${model}, thinking: ${thinkingLevel}) ---`);
+
+	const result = await runSubAgent(prompt, COMPRESSION_SYSTEM_PROMPT, model, thinkingLevel);
+
+	let summary: SessionSummary;
+	if (result.ok) {
+		debugLog(`Summarization succeeded. Response length: ${result.response.length}`);
+		summary = parseSummaryResponse(result.response, observations);
+	} else {
+		debugLog(`Summarization failed: ${result.error}`);
+		summary = extractFallbackSummary(observations);
+	}
+
+	// Override LLM file extraction with deterministic pre-collected files
+	if (context.filesRead) summary.filesRead = context.filesRead;
+	if (context.filesModified) summary.filesModified = context.filesModified;
+
+	return summary;
+}
+
+const COMPRESSION_SYSTEM_PROMPT = `You are a memory compression agent. You observe tool executions from a coding session and produce structured summaries.
+
+Your job is to distill raw tool observations into concise, meaningful memory entries.
+
+Focus on:
+- What was BUILT, FIXED, or LEARNED — not what the observer is doing
+- Use action verbs: implemented, fixed, deployed, configured, migrated
+- Extract key decisions, patterns, and discoveries
+- List all files touched with their read/modified status
+- Tag with relevant concepts from: bugfix, feature, refactor, discovery, how-it-works, problem-solution, architecture, configuration, testing, deployment, performance, security
+
+Skip:
+- Routine operations (empty status checks, simple file listings, package installs)
+- Verbose tool output details
+- Step-by-step narration of what was observed
+
+Output format: structured markdown with these exact section headers:
+## Request
+## What Was Investigated
+## What Was Learned
+## What Was Completed
+## Next Steps
+## Files
+## Concepts`;
+
+/**
+ * Parse the LLM response into a SessionSummary.
+ */
+export function parseSummaryResponse(response: string, observations: Observation[]): SessionSummary {
+	const sections: Record<string, string> = {};
+	let currentSection = "";
+
+	for (const line of response.split("\n")) {
+		const headerMatch = line.match(/^##\s+(.+)/);
+		if (headerMatch) {
+			currentSection = headerMatch[1].trim().toLowerCase();
+			sections[currentSection] = "";
+		} else if (currentSection) {
+			sections[currentSection] = (sections[currentSection] + "\n" + line).trim();
+		}
+	}
+
+	// Extract files
+	const filesText = sections["files"] || "";
+	const filesRead: string[] = [];
+	const filesModified: string[] = [];
+
+	for (const line of filesText.split("\n")) {
+		const readMatch = line.match(/\*\*Read:\*\*\s*(.+)/i);
+		const modMatch = line.match(/\*\*Modified:\*\*\s*(.+)/i);
+		if (readMatch) filesRead.push(...readMatch[1].split(",").map((f) => f.trim()).filter(Boolean));
+		if (modMatch) filesModified.push(...modMatch[1].split(",").map((f) => f.trim()).filter(Boolean));
+	}
+
+	// Extract concepts
+	const conceptsText = sections["concepts"] || "";
+	const concepts = conceptsText.split(/[,\n]/).map((c) => c.trim().replace(/^-\s*/, "")).filter(Boolean);
+
+	return {
+		request: sections["request"] || "Unknown request",
+		investigated: sections["what was investigated"] || "",
+		learned: sections["what was learned"] || "",
+		completed: sections["what was completed"] || "",
+		nextSteps: sections["next steps"] || "",
+		filesRead,
+		filesModified,
+		concepts,
+	};
+}
+
+/**
+ * Extract a basic summary from observations without LLM help.
+ * Uses structured fields (title) from observer-extracted observations.
+ */
+function extractFallbackSummary(observations: Observation[]): SessionSummary {
+	const toolNames = [...new Set(observations.map((o) => o.toolName))];
+	const titles = observations
+		.map((o) => (o.input as any).summary || o.toolName)
+		.filter(Boolean);
+
+	return {
+		request: "Session with tools: " + toolNames.join(", "),
+		investigated: titles.length > 0
+			? titles.slice(0, 10).join("; ")
+			: `Used tools: ${toolNames.join(", ")} across ${observations.length} operations`,
+		learned: "",
+		completed: "",
+		nextSteps: "",
+		filesRead: [],
+		filesModified: [],
+		concepts: [],
+	};
+}

package/config.ts

@@ -0,0 +1,63 @@
+/**
+ * Configuration management for pi-mem.
+ * Loads from ~/.pi/agent/pi-mem.json with fallback to ~/.pi-mem/config.json.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+export interface PiMemConfig {
+	enabled: boolean;
+	autoInject: boolean;
+	maxObservationLength: number;
+	/** Model for observation extraction (e.g. "provider/model-id"). Falls back to summaryModel → session model. */
+	observerModel?: string;
+	/** Model for summarization (e.g. "provider/model-id"). Defaults to the current session model. */
+	summaryModel?: string;
+	/** Thinking level for summarization (e.g. "medium"). Defaults to current session thinking level. */
+	thinkingLevel?: string;
+	indexSize: number;
+	tokenBudget: number;
+	/** Pi provider to use for embeddings (e.g. "openai"). Must support OpenAI-compatible /v1/embeddings. */
+	embeddingProvider?: string;
+	/** Embedding model name (default: "text-embedding-3-small"). */
+	embeddingModel?: string;
+	/** Embedding vector dimensions (default: 1536). Must match the model's output dimensions. */
+	embeddingDims?: number;
+}
+
+const DEFAULTS: PiMemConfig = {
+	enabled: true,
+	autoInject: true,
+	maxObservationLength: 4000,
+	indexSize: 10,
+	tokenBudget: 2000,
+};
+
+export const PI_MEM_DIR = path.join(os.homedir(), ".pi-mem");
+
+const CONFIG_PATHS = [
+	path.join(os.homedir(), ".pi", "agent", "pi-mem.json"),
+	path.join(PI_MEM_DIR, "config.json"),
+];
+
+export function loadConfig(): PiMemConfig {
+	for (const configPath of CONFIG_PATHS) {
+		try {
+			if (fs.existsSync(configPath)) {
+				const raw = fs.readFileSync(configPath, "utf-8");
+				const userConfig = JSON.parse(raw);
+				// Support both "model" and "summaryModel" keys
+				if (userConfig.model && !userConfig.summaryModel) {
+					userConfig.summaryModel = userConfig.model;
+				}
+				return { ...DEFAULTS, ...userConfig };
+			}
+		} catch {
+			// Ignore parse errors, try next
+		}
+	}
+
+	return { ...DEFAULTS };
+}

package/context-injection.ts

@@ -0,0 +1,92 @@
+/**
+ * Context injection for pi-mem.
+ * Queries LanceDB for recent summaries, prompt-aware semantic search,
+ * and injects 3-layer workflow guidance.
+ */
+
+import type { PiMemConfig } from "./config.js";
+import {
+	getRecentSummaries,
+	semanticSearch,
+	type ObservationStore,
+} from "./observation-store.js";
+
+/**
+ * Estimate token count from text (~4 chars per token).
+ */
+function estimateTokens(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+const WORKFLOW_GUIDANCE = `### Memory Search Tools
+
+3-LAYER WORKFLOW (ALWAYS FOLLOW):
+1. search(query) → Get index with IDs (~50-100 tokens/result)
+2. timeline(anchor=ID) → Get context around interesting results
+3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
+NEVER fetch full details without filtering first. 10x token savings.`;
+
+/**
+ * Build the injected context for before_agent_start.
+ * Returns null if no context is available.
+ */
+export async function buildInjectedContext(
+	store: ObservationStore | null,
+	projectSlug: string,
+	config: PiMemConfig,
+	userPrompt?: string,
+): Promise<string | null> {
+	if (!config.autoInject) return null;
+
+	let budget = config.tokenBudget;
+	const parts: string[] = [];
+
+	// 1. Recent summaries index (highest priority)
+	if (store?.available) {
+		try {
+			const summaries = await getRecentSummaries(store, projectSlug, config.indexSize);
+			if (summaries.length > 0) {
+				const indexSection =
+					`## Project Memory (${projectSlug})\n\n` +
+					summaries
+						.map((s) => `- ${s.timestamp.slice(0, 10)} [${s.session_id}]: ${s.title}`)
+						.join("\n");
+				const tokens = estimateTokens(indexSection);
+				if (tokens <= budget) {
+					parts.push(indexSection);
+					budget -= tokens;
+				}
+			}
+		} catch {
+			// Graceful degradation
+		}
+	}
+
+	// 2. Prompt-aware semantic search results (if available)
+	if (store?.available && store.embed && userPrompt && budget > 200) {
+		try {
+			const results = await semanticSearch(store, userPrompt, projectSlug, 2);
+			for (const result of results) {
+				const maxChars = budget * 4;
+				const snippet = `### Relevant: ${result.timestamp.slice(0, 10)} [${result.session_id}]\n${result.narrative.slice(0, maxChars)}`;
+				const tokens = estimateTokens(snippet);
+				if (tokens > budget) break;
+				parts.push(snippet);
+				budget -= tokens;
+			}
+		} catch {
+			// Graceful degradation
+		}
+	}
+
+	// 3. Workflow guidance (always included if there's budget)
+	const guidanceTokens = estimateTokens(WORKFLOW_GUIDANCE);
+	if (guidanceTokens <= budget) {
+		parts.push(WORKFLOW_GUIDANCE);
+		budget -= guidanceTokens;
+	}
+
+	if (parts.length === 0) return null;
+
+	return parts.join("\n\n");
+}