@henryqw/pi-memory 0.1.0 → 0.2.2

package/README.md

@@ -2,6 +2,12 @@
 
 Auto-managed markdown memory for Pi: two size-capped entry stores (`MEMORY.md`, `USER.md`) with a frozen system-prompt snapshot per session.
 
+## Why
+
+- **Created for**: Giving Pi compact global notes and user facts that survive across sessions.
+- **Advantage**: Size-capped, auto-managed Markdown stores provide predictable prompt cost without a hand-maintained knowledge tree.
+- **Inspired by**: [Hermes Agent](https://github.com/NousResearch/hermes-agent) and its bounded `MEMORY.md`/`USER.md` cross-session memory pattern.
+
 ## Install
 
 ```bash
@@ -41,6 +47,8 @@ Invalid configuration fails fast; malformed config files are never rewritten.
 
 Point `directory` at an iCloud Drive or Obsidian-vault-synced folder. The synced vault acts as a dumb sync pipe: pi-memory owns the file format and treats the remote as opaque storage, so no merge logic runs on the Pi side.
 
+Backups and the lock file live outside `directory`, under `~/.pi/agent/backups/pi-memory/`.
+
 ## Threat model
 
 Because the directory can be a globally synced location readable outside Pi, review [`ADR 006 — pi-memory global store threat model`](https://github.com/HenryQW/pi-packages/blob/main/docs/adr/006-pi-memory-global-store-threat-model.md) before pointing it at a shared or cloud-synced path.

package/extensions/memory.ts

@@ -2,6 +2,7 @@ import { mkdir, readdir, realpath } from "node:fs/promises";
 import { join, sep } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { getAgentDir, withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { lock } from "proper-lockfile";
 import { Type } from "typebox";
 import { loadMemoryConfig, type MemoryConfig } from "../src/config.ts";
@@ -10,10 +11,11 @@ import { ENTRY_DELIMITER, MemoryStore, type Target } from "../src/store.ts";
 const SEPARATOR = "═".repeat(46);
 // Backups and the lock file live OUTSIDE config.directory (which may be
 // iCloud-synced) so the memory dir holds exactly MEMORY.md and USER.md (ADR 005).
-const BACKUP_DIR = () => join(getAgentDir(), "memory-backups");
+const BACKUP_DIR = () => join(getAgentDir(), "backups", "pi-memory");
 // Defense-in-depth against snapshot frame spoofing by poisoned on-disk entries.
 const FRAME_TOKEN_LINE = /^\s*(?:═{3,}|MEMORY \(your personal notes|USER PROFILE \(who the user is)/;
 const FRAME_TOKEN_REPLACEMENT = "[filtered frame token]";
+const DISPLAY_CONTROL_CHARACTER = /[\p{Cc}\p{Cf}]/gu;
 // @henryqw/pi-herdr-btw does not export internal/core.ts from its package root.
 const BTW_CHILD_PAYLOAD_ARG = "--pi-herdr-btw-payload";
 const CONSOLIDATION_FAILURE = /(?:exceed|over) the limit|would put memory|no entry matched|[Mm]ultiple entries matched|matched multiple distinct/i;
@@ -41,6 +43,16 @@ function sanitizeName(name: string): string {
 	return name.replace(/[\p{C}]/gu, "").slice(0, 120);
 }
 
+function escapeDisplayControls(text: string): string {
+	return text.replace(DISPLAY_CONTROL_CHARACTER, (character) => {
+		if (character === "\n") return character;
+		const codePoint = character.codePointAt(0)!;
+		return codePoint <= 0xffff
+			? `\\u${codePoint.toString(16).padStart(4, "0")}`
+			: `\\u{${codePoint.toString(16)}}`;
+	});
+}
+
 function renderBlock(target: Target, entries: string[], config: MemoryConfig, warnings: string[]): string {
 	if (!entries.length) return "";
 	const limit = target === "user" ? config.userCharLimit : config.memoryCharLimit;
@@ -231,13 +243,26 @@ export default function memoryExtension(pi: ExtensionAPI): void {
 								message: "Write saved. This update is complete — do not repeat it.",
 							}),
 						}],
-						details: {},
+						details: { status: result.message ?? "Write saved.", entries: result.writtenEntries ?? [] },
 					};
 				} finally {
 					await release();
 				}
 			});
 		},
+
+		renderResult(result, _options, theme, _context) {
+			const details = result.details as { status: string; entries: string[] } | undefined;
+			if (!details) {
+				const content = result.content[0];
+				return new Text(content?.type === "text" ? content.text : "", 0, 0);
+			}
+			let text = theme.fg("success", `✓ ${details.status}`);
+			for (const entry of details.entries) {
+				text += `\n  ${theme.fg("accent", escapeDisplayControls(entry).replaceAll("\n", "\n  "))}`;
+			}
+			return new Text(text, 0, 0);
+		},
 	});
 
 	pi.on("before_agent_start", (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-memory",
-	"version": "0.1.0",
+	"version": "0.2.2",
 	"description": "Auto-managed markdown memory for Pi: capped MEMORY.md/USER.md entry stores with frozen session snapshots.",
 	"keywords": [
 		"pi-package",
@@ -29,6 +29,7 @@
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "^0.84.2",
 		"@earendil-works/pi-coding-agent": "^0.84.2",
+		"@earendil-works/pi-tui": "^0.84.2",
 		"typebox": "^1.3.15"
 	},
 	"devDependencies": {

package/src/store.ts

@@ -45,6 +45,7 @@ type Result = {
 	error?: string;
 	usage?: string;
 	entryCount?: number;
+	writtenEntries?: string[];
 	currentEntries?: string[];
 	matches?: string[];
 	done?: boolean;
@@ -127,7 +128,7 @@ export class MemoryStore {
 		return `${pct}% — ${current.toLocaleString()}/${limit.toLocaleString()} chars`;
 	}
 
-	private successResponse(target: Target, message?: string): Result {
+	private successResponse(target: Target, message?: string, writtenEntries: string[] = []): Result {
 		this.resetOnSuccess();
 		return {
 			success: true,
@@ -136,6 +137,7 @@ export class MemoryStore {
 			message,
 			usage: this.usage(target),
 			entryCount: this.entries.get(target)!.length,
+			writtenEntries,
 			note: "Write saved. This update is complete — do not repeat it.",
 		};
 	}
@@ -392,7 +394,7 @@ export class MemoryStore {
 		const entries = this.entries.get(target)!;
 
 		if (entries.includes(text)) {
-			return this.successResponse(target, "Entry already exists (no duplicate added).");
+			return this.successResponse(target, "Entry already exists (no duplicate added).", [text]);
 		}
 
 		const newTotal = [...entries, text].join(ENTRY_DELIMITER).length;
@@ -408,7 +410,7 @@ export class MemoryStore {
 
 		entries.push(text);
 		await this.persist(target);
-		return this.successResponse(target, "Entry added.");
+		return this.successResponse(target, "Entry added.", [text]);
 	}
 
 	private unreadableAbort(target: Target): Result {
@@ -467,7 +469,7 @@ export class MemoryStore {
 
 		this.entries.set(target, deduped);
 		await this.persist(target);
-		return this.successResponse(target, "Entry replaced.");
+		return this.successResponse(target, "Entry replaced.", [text]);
 	}
 
 	async remove(target: Target, oldText: string): Promise<Result> {
@@ -557,6 +559,10 @@ export class MemoryStore {
 
 		this.entries.set(target, working);
 		await this.persist(target);
-		return this.successResponse(target, `Applied ${operations.length} operation(s).`);
+		const writtenEntries = [...new Set(operations.flatMap((operation) => {
+			const content = normalize(operation.content ?? operation.new_text ?? "");
+			return (operation.action === "add" || operation.action === "replace") && working.includes(content) ? [content] : [];
+		}))];
+		return this.successResponse(target, `Applied ${operations.length} operation(s).`, writtenEntries);
 	}
 }