@askjo/pi-mem 1.0.0 → 1.2.0

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: skyfallsin

package/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: npm-publish
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+      - name: Verify tag matches package.json version
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) != package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+      - run: npm ci --ignore-scripts
+      - name: Publish with provenance
+        run: npm publish --provenance --access public

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jo-inc
+
+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

@@ -1,3 +1,8 @@
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://www.npmjs.com/package/@askjo/pi-mem"><img src="https://img.shields.io/npm/v/@askjo/pi-mem" alt="npm version" /></a>
+  <a href="https://github.com/jo-inc/pi-mem/stargazers"><img src="https://img.shields.io/github/stars/jo-inc/pi-mem" alt="GitHub stars" /></a>
+</p>
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png" />
@@ -48,12 +53,32 @@ Files in `notes/` and older daily logs are **not** injected — they're accessib
 
 ## Configuration
 
+Settings can be configured via environment variables or a `.pi-mem.json` file in the memory directory. Environment variables take precedence over file values.
+
+### .pi-mem.json
+
+Place a `.pi-mem.json` in your memory directory (default `~/.pi/agent/memory/.pi-mem.json`):
+
+```json
+{
+  "searchDirs": ["catchup", "projects"],
+  "contextFiles": ["SOUL.md", "AGENTS.md"],
+  "autocommit": true
+}
+```
+
+### Environment variables
+
+Environment variables override `.pi-mem.json` values when set.
+
 | Env Var | Default | Description |
 |---------|---------|-------------|
 | `PI_MEMORY_DIR` | `~/.pi/agent/memory/` | Root directory for all memory files |
 | `PI_DAILY_DIR` | `$PI_MEMORY_DIR/daily/` | Directory for daily logs |
 | `PI_CONTEXT_FILES` | *(empty)* | Comma-separated list of extra files to inject into context (e.g. `SOUL.md,AGENTS.md,HEARTBEAT.md`) |
+| `PI_SEARCH_DIRS` | *(empty)* | Comma-separated list of subdirectories (relative to `PI_MEMORY_DIR`) to include in `memory_search`. Searched recursively one level deep. (e.g. `catchup,projects`) |
 | `PI_AUTOCOMMIT` | `false` | When `1` or `true`, auto-commit to git after every write |
+| `PI_TIMEZONE` | `TZ`, then `UTC` | IANA timezone used for daily log filenames and today/yesterday context windows. Invalid values fall back to `UTC`. |
 
 ## Dashboard Widget
 
@@ -76,3 +101,13 @@ pi install git:github.com/jo-inc/pi-mem
 ## License
 
 MIT
+
+## Pi Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [pi-reflect](https://github.com/jo-inc/pi-reflect) | Self-improving behavioral files |
+| [pi-boss](https://github.com/skyfallsin/pi-boss) | Multi-agent orchestration via tmux |
+| [pi-room](https://github.com/skyfallsin/pi-room) | Multi-agent awareness and coordination |
+| [pi-vertex-anthropic](https://github.com/skyfallsin/pi-vertex-anthropic) | Claude via Google Cloud Vertex AI |
+| [pi-skill-posthog](https://github.com/skyfallsin/pi-skill-posthog) | PostHog analytics skill for pi agents |

package/index.ts

@@ -24,8 +24,8 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
-import { Markdown } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { StringEnum, completeSimple, getModel } from "@mariozechner/pi-ai";
 import * as fs from "node:fs";
@@ -47,9 +47,11 @@ import {
 	parseScratchpad,
 	serializeScratchpad,
 	buildMemoryContext,
+	readMemoryFile,
 	scanSession,
 	isHousekeeping,
 	searchMemory,
+	resolveSessionsDir,
 } from "./lib.ts";
 
 const config = buildConfig();
@@ -66,7 +68,7 @@ function gitCommit(message: string) {
 
 // --- Session scanner for "Last 24h" dashboard ---
 
-const SESSIONS_DIR = path.join(process.env.HOME ?? "~", ".pi", "agent", "sessions");
+const SESSIONS_DIR = resolveSessionsDir();
 const SUMMARY_CACHE = path.join(config.dailyDir, "cache.json");
 const REBUILD_INTERVAL_MS = 15 * 60 * 1000;
 const LOOKBACK_MS = 24 * 60 * 60 * 1000;
@@ -127,13 +129,13 @@ async function summarizeWithLLM(sessions: SessionInfo[], childCountMap: Map<stri
 	];
 
 	let model: any = null;
-	let apiKey: string | undefined;
+	let auth: { ok: true; apiKey?: string; headers?: Record<string, string> } | undefined;
 	for (const candidate of candidates) {
 		if (!candidate) continue;
-		const key = await modelRegistryRef.getApiKey(candidate);
-		if (key) { model = candidate; apiKey = key; break; }
+		const result = await modelRegistryRef.getApiKeyAndHeaders(candidate);
+		if (result.ok) { model = candidate; auth = result; break; }
 	}
-	if (!model || !apiKey) return "";
+	if (!model || !auth) return "";
 
 	const listing = sessions.map((s, _i) => {
 		const childCount = childCountMap.get(s.file) || 0;
@@ -165,7 +167,7 @@ async function summarizeWithLLM(sessions: SessionInfo[], childCountMap: Map<stri
 			content: [{ type: "text" as const, text: `${sessions.length} sessions, $${totalCost.toFixed(2)} total cost:\n\n${listing}` }],
 			timestamp: Date.now(),
 		}],
-	}, { apiKey });
+	}, { apiKey: auth.apiKey, headers: auth.headers });
 
 	return response.content
 		.filter((c: any) => c.type === "text")
@@ -240,32 +242,77 @@ export default function (pi: ExtensionAPI) {
 		const summary = await getOrRebuildSummary();
 		const scratchContent = readFileSafe(config.scratchpadFile);
 
-		const sections: string[] = [];
-
-		if (summary) {
-			sections.push(summary);
-		}
-
+		// Parse scratchpad items
+		const openItems: string[] = [];
 		if (scratchContent?.trim()) {
-			const items = scratchContent
-				.trim()
-				.split("\n")
-				.filter((l: string) => l.match(/^- \[ \]/))
-				.filter((l: string) => !l.match(/^<!--.*-->$/))
-				.map((l: string) => l.replace(/^- /, ""));
-			if (items.length > 0) {
-				sections.push(`## Scratchpad\n\n${items.join("\n")}`);
+			const lines = scratchContent.trim().split("\n");
+			for (const l of lines) {
+				if (l.match(/^- \[ \]/) && !l.match(/^<!--.*-->$/)) {
+					openItems.push(l.replace(/^- /, ""));
+				}
 			}
 		}
 
-		if (sections.length === 0) return;
+		if (!summary && openItems.length === 0) return;
 
-		const md = sections.join("\n\n---\n\n");
-
-		ctx.ui.setWidget("memory-dashboard", (_tui: any, _theme: any) => {
+		ctx.ui.setWidget("memory-dashboard", (_tui: any, theme: any) => {
 			const mdTheme = getMarkdownTheme();
-			const markdown = new Markdown(md, 1, 0, mdTheme);
-			return markdown;
+			const container = new Container();
+			let cachedWidth: number | undefined;
+			let cachedLines: string[] | undefined;
+			let lastExpanded: boolean | undefined;
+
+			const origRender = container.render.bind(container);
+			container.render = (width: number) => {
+				const expanded = ctx.ui.getToolsExpanded();
+
+				if (cachedLines && cachedWidth === width && lastExpanded === expanded) {
+					return cachedLines;
+				}
+
+				container.clear();
+
+				if (expanded) {
+					if (summary) {
+						container.addChild(new Markdown(summary, 1, 0, mdTheme));
+					}
+					if (openItems.length > 0) {
+						if (summary) container.addChild(new Spacer(1));
+						const scratchMd = `## Scratchpad\n\n${openItems.join("\n")}`;
+						container.addChild(new Markdown(scratchMd, 1, 0, mdTheme));
+					}
+				} else {
+					const parts: string[] = [];
+					if (summary) {
+						const costMatch = summary.match(/\$[\d.]+/);
+						const cost = costMatch ? costMatch[0] : "";
+						const sessMatch = summary.match(/(\d+) sessions/);
+						const sessions = sessMatch ? sessMatch[1] : "0";
+						parts.push(`Last 24h: ${cost}, ${sessions} log entries`);
+					}
+					if (openItems.length > 0) {
+						parts.push(`${openItems.length} scratchpad item${openItems.length > 1 ? "s" : ""}`);
+					}
+					const hint = keyHint("expandTools", "to expand");
+					const line = theme.fg("muted", parts.join(", ")) + " " + theme.fg("dim", `(${hint})`);
+					container.addChild(new Text(line, 1, 0));
+				}
+
+				cachedLines = origRender(width);
+				cachedWidth = width;
+				lastExpanded = expanded;
+				return cachedLines;
+			};
+
+			const origInvalidate = container.invalidate.bind(container);
+			container.invalidate = () => {
+				cachedWidth = undefined;
+				cachedLines = undefined;
+				lastExpanded = undefined;
+				origInvalidate();
+			};
+
+			return container;
 		});
 	}
 
@@ -298,23 +345,38 @@ export default function (pi: ExtensionAPI) {
 		if (rebuildTimer) { clearInterval(rebuildTimer); rebuildTimer = null; }
 	});
 
-	pi.on("before_agent_start", async (event, _ctx) => {
+	// Inject memory as a trailing user message, leaving the stable system prompt
+	// untouched for prompt caching. Pi 0.81 drops unsupported system-role entries.
+	pi.on("context", async (event) => {
 		const memoryContext = buildMemoryContext(config);
-		if (!memoryContext) return;
 
 		const memoryInstructions = [
-			"\n\n## Memory",
+			"## Memory",
 			"The following memory files have been loaded. Use the memory_write tool to persist important information.",
 			"- Decisions, preferences, and durable facts \u2192 MEMORY.md",
 			"- Day-to-day notes and running context \u2192 daily/<YYYY-MM-DD>.md",
 			"- Things to fix later or keep in mind \u2192 scratchpad tool",
+			"- Scratchpad is NOT auto-loaded. Use memory_read(target='scratchpad') to fetch it when needed.",
 			'- If someone says "remember this," write it immediately.',
 			"",
+			"### Daily Log Rule",
+			"After meaningful interactions, call memory_write(target='daily') with a brief 1-2 sentence summary.",
+			"**Log when:** task completed, decision made, bug fixed, new info discovered, config changed.",
+			"**Skip when:** greetings, goodbyes, chitchat, simple acks, trivial factual questions.",
+			"Log the outcome, not the question (e.g. \"Debugged import error \u2014 missing __init__.py\" not \"User asked about imports\").",
+			"",
 			memoryContext,
 		].join("\n");
 
 		return {
-			systemPrompt: event.systemPrompt + memoryInstructions,
+			messages: [
+				...event.messages,
+				{
+					role: "user" as const,
+					content: `<pi-mem-injected>\n${memoryInstructions}\n</pi-mem-injected>`,
+					timestamp: Date.now(),
+				},
+			],
 		};
 	});
 
@@ -387,35 +449,29 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (target === "daily") {
-				const filePath = dailyPath(config.dailyDir, todayStr());
+				const date = todayStr(config.timezone);
+				const filePath = dailyPath(config.dailyDir, date);
 				const existing = readFileSafe(filePath) ?? "";
 
-				const existingSnippet = existing.trim()
-					? `\n\nExisting daily log content:\n${existing.trim()}`
-					: "\n\nDaily log was empty.";
-
 				const separator = existing.trim() ? "\n\n" : "";
 				const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
 				fs.writeFileSync(filePath, existing + separator + stamped, "utf-8");
-				gitCommit(`daily: ${todayStr()}`);
+				gitCommit(`daily: ${date}`);
 				return {
-					content: [{ type: "text", text: `Appended to daily log: ${filePath}${existingSnippet}` }],
+					content: [{ type: "text", text: `Appended to daily/${date}.md` }],
 					details: { path: filePath, target, mode: "append", sessionId: sid, timestamp: ts },
 				};
 			}
 
 			// long_term
 			const existing = readFileSafe(config.memoryFile) ?? "";
-			const existingSnippet = existing.trim()
-				? `\n\nExisting MEMORY.md content:\n${existing.trim()}`
-				: "\n\nMEMORY.md was empty.";
 
 			if (mode === "overwrite") {
 				const stamped = `<!-- last updated: ${ts} [${sid}] -->\n${content}`;
 				fs.writeFileSync(config.memoryFile, stamped, "utf-8");
 				gitCommit("memory: overwrite");
 				return {
-					content: [{ type: "text", text: `Overwrote MEMORY.md${existingSnippet}` }],
+					content: [{ type: "text", text: `Overwrote MEMORY.md` }],
 					details: { path: config.memoryFile, target, mode: "overwrite", sessionId: sid, timestamp: ts },
 				};
 			}
@@ -425,7 +481,7 @@ export default function (pi: ExtensionAPI) {
 			fs.writeFileSync(config.memoryFile, existing + separator + stamped, "utf-8");
 			gitCommit("memory: append");
 			return {
-				content: [{ type: "text", text: `Appended to MEMORY.md${existingSnippet}` }],
+				content: [{ type: "text", text: `Appended to MEMORY.md` }],
 				details: { path: config.memoryFile, target, mode: "append", sessionId: sid, timestamp: ts },
 			};
 		},
@@ -536,7 +592,7 @@ export default function (pi: ExtensionAPI) {
 			"- 'long_term': Read MEMORY.md",
 			"- 'scratchpad': Read SCRATCHPAD.md",
 			"- 'daily': Read a specific day's log (default: today). Pass date as YYYY-MM-DD.",
-			"- 'file': Read any file by name (e.g. 'SOUL.md'). Pass filename.",
+			"- 'file': Read any file by exact path (e.g. 'SOUL.md', 'catchup/2026-04-26/file.md'). Pass filename. If the exact file is missing and the directory has an INDEX.md with <!-- file:... --> entries, I resolve by title/query within that index.",
 			"- 'note': Read a file from notes/ (e.g. 'lessons.md'). Pass filename.",
 			"- 'list': List all files in the memory directory.",
 		].join("\n"),
@@ -550,6 +606,7 @@ export default function (pi: ExtensionAPI) {
 			filename: Type.Optional(
 				Type.String({ description: "Filename for 'file' target (e.g. 'lessons.md', 'SOUL.md')" }),
 			),
+
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			ensureDirs(config);
@@ -569,6 +626,13 @@ export default function (pi: ExtensionAPI) {
 					const dailyFiles = fs.readdirSync(config.dailyDir).filter(f => f.endsWith(".md")).sort().reverse();
 					if (dailyFiles.length > 0) sections.push(`Daily logs (${dailyFiles.length}):\n${dailyFiles.slice(0, 10).map(f => `- daily/${f}`).join("\n")}${dailyFiles.length > 10 ? `\n  ... and ${dailyFiles.length - 10} more` : ""}`);
 				} catch {}
+				try {
+					const catchupDir = path.join(config.memoryDir, "catchup");
+					const catchupDates = fs.readdirSync(catchupDir).filter(f => {
+						try { return fs.statSync(path.join(catchupDir, f)).isDirectory(); } catch { return false; }
+					}).sort().reverse();
+					if (catchupDates.length > 0) sections.push(`Catchup (${catchupDates.length} dates):\n${catchupDates.slice(0, 10).map(d => `- catchup/${d}/`).join("\n")}${catchupDates.length > 10 ? `\n  ... and ${catchupDates.length - 10} more` : ""}`);
+				} catch {}
 				if (sections.length === 0) {
 					return { content: [{ type: "text", text: "Memory directory is empty." }], details: {} };
 				}
@@ -579,13 +643,8 @@ export default function (pi: ExtensionAPI) {
 				if (!filename) {
 					return { content: [{ type: "text", text: "Error: 'filename' is required for target 'file'." }], details: {} };
 				}
-				const safe = path.basename(filename);
-				const filePath = path.join(config.memoryDir, safe);
-				const content = readFileSafe(filePath);
-				if (!content) {
-					return { content: [{ type: "text", text: `File not found: ${safe}` }], details: {} };
-				}
-				return { content: [{ type: "text", text: content }], details: { path: filePath, filename: safe } };
+				const result = readMemoryFile(config, filename);
+				return { content: [{ type: "text", text: result.text }], details: result.details };
 			}
 
 			if (target === "note") {
@@ -602,7 +661,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (target === "daily") {
-				const d = date ?? todayStr();
+				const d = date ?? todayStr(config.timezone);
 				const filePath = dailyPath(config.dailyDir, d);
 				const content = readFileSafe(filePath);
 				if (!content) {