@henryqw/pi-memory 1.0.0 → 1.1.0

package/README.md

@@ -18,11 +18,12 @@ pi install npm:@henryqw/pi-memory
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
+| `/remember <instruction>` | command | Process an instruction into compact durable memory, deduplicating against live entries. |
 | `memory` | tool | Add, replace, remove, or batch-edit entries across sessions. |
 
 The extension maintains two markdown stores: `MEMORY.md` (global agent notes shared across all projects — do not store project-specific facts here, those belong in the repo) and `USER.md` (user profile). Each file holds `§`-delimited entries and is size-capped — 8800 characters by default for `MEMORY.md`, 5500 for `USER.md`. When a write would exceed the cap, the tool rejects it and reports current usage; consolidate by issuing one batch that removes or shortens stale entries and adds the new entry together (batch checks the final size only). If the on-disk file exceeds the cap (external edit or sync), the session snapshot omits the overflow and warns instead of injecting it.
 
-At session start, the current contents of both stores are frozen into the system prompt; later edits during the session do not alter what the model already saw.
+At session start, the current contents of both stores are frozen into the system prompt; later edits during the session do not alter what the model already saw. Use `/remember <instruction>` to ask the agent to normalize and deduplicate an instruction against the live contents of both stores before using the memory tool; unsuitable project-specific, temporary, trivial, or otherwise unsuitable content is refused. Each turn also includes a short memory check: save explicit durable preferences or corrections immediately, inferred habits after two independent signals from the conversation and/or existing profile, merge overlaps, and skip project- or repository-specific facts, task-local behavior, progress, and temporary preferences.
 
 To inspect live state, read `<directory>/MEMORY.md`.
 

package/extensions/memory.ts

@@ -6,7 +6,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { lock } from "proper-lockfile";
 import { Type } from "typebox";
 import { configPath, loadMemoryConfig, type MemoryConfig } from "../src/config.ts";
-import { ENTRY_DELIMITER, MemoryStore, type Target } from "../src/store.ts";
+import { ENTRY_DELIMITER, MemoryStore, usage, type Target } from "../src/store.ts";
 
 const SEPARATOR = "═".repeat(46);
 // Backups and the lock file live OUTSIDE config.directory (which may be
@@ -19,6 +19,8 @@ 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;
+const MEMORY_CHECK = "MEMORY CHECK: Save explicit durable user preferences or corrections immediately. Save an inferred habit only after two independent signals from the conversation and/or existing profile. Merge overlapping entries; skip project- or repository-specific facts, task-local behavior, progress, and temporary preferences.";
+const REMEMBER_USAGE = "Usage: /remember <instruction>";
 const MEMORY_DESCRIPTION = `Save durable facts to persistent memory that survive across sessions. Memory is injected into every future turn, so keep entries compact and high-signal.
 
 HOW: Prefer one operations batch for multiple changes or consolidation. A batch applies atomically and checks the character limit only on the final result, so it can remove or shorten stale entries and add new ones in one call. Use action/content/old_text only for one lone change. A successful response finishes the update; do not repeat it.
@@ -87,31 +89,9 @@ function renderBlock(target: Target, entries: string[], config: MemoryConfig, wa
 	// Everything omitted (e.g. one entry larger than the whole cap): no block,
 	// the standalone warning above still reaches the prompt.
 	if (!kept.length) return "";
-	const usage = `${Math.min(100, Math.floor((used / limit) * 100))}% — ${used.toLocaleString()}/${limit.toLocaleString()} chars`;
+	const usageText = usage(used, limit);
 	const header = target === "user" ? "USER PROFILE (who the user is)" : "MEMORY (your personal notes)";
-	return `${SEPARATOR}\n${header} [${usage}]\n${SEPARATOR}\n${content}`;
-}
-
-// Bound aggregate preview size: thousands of short entries over cap must not
-// inject nearly the whole file into one tool error.
-function failureMessage(error: string, entries?: string[]): string {
-	if (!entries?.length) return error;
-	const MAX_PREVIEW_ENTRIES = 20;
-	const MAX_PREVIEW_CHARS = 1500;
-	const shown: string[] = [];
-	let chars = 0;
-	let moreEntries = 0;
-	for (const entry of entries) {
-		const clipped = entry.length > 120 ? `${entry.slice(0, 120)}...` : entry;
-		if (shown.length >= MAX_PREVIEW_ENTRIES || chars + clipped.length > MAX_PREVIEW_CHARS) {
-			moreEntries = entries.length - shown.length;
-			break;
-		}
-		shown.push(clipped);
-		chars += clipped.length;
-	}
-	const suffix = moreEntries > 0 ? ` (and ${moreEntries} more entries)` : "";
-	return `${error}\nCurrent entries: ${JSON.stringify(shown)}${suffix}`;
+	return `${SEPARATOR}\n${header} [${usageText}]\n${SEPARATOR}\n${content}`;
 }
 
 export default function memoryExtension(pi: ExtensionAPI): void {
@@ -123,6 +103,53 @@ export default function memoryExtension(pi: ExtensionAPI): void {
 		initError?: string;
 	} = { conflictWarnings: [] };
 
+	pi.registerCommand("remember", {
+		description: "Process an instruction into durable memory",
+		handler: async (args, ctx) => {
+			const candidate = args.trim();
+			if (!candidate) {
+				ctx.ui.notify(REMEMBER_USAGE, "warning");
+				return;
+			}
+			if (!ctx.isIdle()) {
+				ctx.ui.notify("Cannot run /remember while the agent is busy.", "warning");
+				return;
+			}
+			if (state.initError) {
+				ctx.ui.notify(`Cannot run /remember: persistent memory is disabled — ${sanitizeName(state.initError)}`, "warning");
+				return;
+			}
+			if (!state.config || !state.stores) {
+				ctx.ui.notify("Cannot run /remember: persistent memory is not initialized.", "warning");
+				return;
+			}
+			try {
+				const loaded = await Promise.all((Object.keys(state.stores) as Target[]).map(async (target) => [target, await state.stores![target].load(target)] as const));
+				const invalid = loaded.filter(([, result]) => result.status);
+				if (invalid.length) {
+					ctx.ui.notify(`Cannot run /remember: live memory state is unreadable or oversized. ${invalid.map(([, result]) => result.conflictWarning).join(" ")}`, "warning");
+					return;
+				}
+				if (!ctx.isIdle()) {
+					ctx.ui.notify("Cannot run /remember while the agent is busy.", "warning");
+					return;
+				}
+				const overLimit = loaded.filter(([target, result]) => {
+					const limit = target === "user" ? state.config!.userCharLimit : state.config!.memoryCharLimit;
+					return result.entries.join(ENTRY_DELIMITER).length > limit;
+				});
+				if (overLimit.length) {
+					ctx.ui.notify(`Cannot run /remember: live ${overLimit.map(([target]) => target).join(" and ")} entries exceed the configured character limit. Consolidate them before using /remember.`, "warning");
+					return;
+				}
+				const entries = Object.fromEntries(loaded.map(([target, result]) => [target, result.entries]));
+				pi.sendUserMessage(`Process this /remember instruction; do not blindly copy it. Normalize the candidate into compact durable memory, choose the correct memory target, semantically compare it with the live entries, and merge or replace overlap instead of adding duplicates. Use the existing memory tool. Refuse project/repository-specific, temporary, trivial, or otherwise unsuitable content.\n\nCandidate:\n${JSON.stringify(candidate)}\n\nLive entries by target:\n${JSON.stringify(entries)}`);
+			} catch (error) {
+				ctx.ui.notify(`Cannot run /remember: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			}
+		},
+	});
+
 	pi.on("session_start", async () => {
 		state.config = undefined;
 		state.stores = undefined;
@@ -229,7 +256,8 @@ export default function memoryExtension(pi: ExtensionAPI): void {
 						if (CONSOLIDATION_FAILURE.test(error) && store.incrementFailure().done) {
 							throw new Error("Memory consolidation failed repeatedly this turn. Stop retrying memory calls, continue replying to the user.");
 						}
-						throw new Error(failureMessage(error, result.currentEntries));
+						if (result.currentEntries?.length) error += `\nCurrent entries: ${JSON.stringify(result.currentEntries)}`;
+						throw new Error(error);
 					}
 					store.resetOnSuccess();
 					return {
@@ -275,6 +303,6 @@ export default function memoryExtension(pi: ExtensionAPI): void {
 		}
 		if (!state.config || !state.stores || !state.snapshotBlocks) return;
 		const blocks = [...state.snapshotBlocks, ...state.conflictWarnings].filter(Boolean).join("\n\n");
-		return { systemPrompt: `${event.systemPrompt}\n\n${blocks}` };
+		return { systemPrompt: `${event.systemPrompt}\n\n${blocks ? `${blocks}\n\n` : ""}${MEMORY_CHECK}` };
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-memory",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Auto-managed markdown memory for Pi: capped MEMORY.md/USER.md entry stores with frozen session snapshots.",
 	"keywords": [
 		"pi-package",

package/src/config.ts

@@ -19,6 +19,14 @@ export function DEFAULT_DIRECTORY(): string {
 export const DEFAULT_MEMORY_CHAR_LIMIT = 8800;
 export const DEFAULT_USER_CHAR_LIMIT = 5500;
 
+function charLimit(key: "memoryCharLimit" | "userCharLimit", value: unknown, defaultValue: number, path: string): number {
+	if (value === undefined) return defaultValue;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > 100_000) {
+		throw new Error(`Invalid '${key}' in memory config at ${path}: must be a positive safe integer <= 100000, got ${JSON.stringify(value)}`);
+	}
+	return value;
+}
+
 export function loadMemoryConfig(explicitPath?: string): MemoryConfig {
 	const path = explicitPath ?? configPath();
 	let raw: string;
@@ -87,23 +95,8 @@ export function loadMemoryConfig(explicitPath?: string): MemoryConfig {
 		directory = obj.directory;
 	}
 
-	let memoryCharLimit = DEFAULT_MEMORY_CHAR_LIMIT;
-	if (obj.memoryCharLimit !== undefined) {
-		const val = obj.memoryCharLimit;
-		if (typeof val !== "number" || !Number.isSafeInteger(val) || val <= 0 || val > 100_000) {
-			throw new Error(`Invalid 'memoryCharLimit' in memory config at ${path}: must be a positive safe integer <= 100000, got ${JSON.stringify(val)}`);
-		}
-		memoryCharLimit = val;
-	}
-
-	let userCharLimit = DEFAULT_USER_CHAR_LIMIT;
-	if (obj.userCharLimit !== undefined) {
-		const val = obj.userCharLimit;
-		if (typeof val !== "number" || !Number.isSafeInteger(val) || val <= 0 || val > 100_000) {
-			throw new Error(`Invalid 'userCharLimit' in memory config at ${path}: must be a positive safe integer <= 100000, got ${JSON.stringify(val)}`);
-		}
-		userCharLimit = val;
-	}
+	const memoryCharLimit = charLimit("memoryCharLimit", obj.memoryCharLimit, DEFAULT_MEMORY_CHAR_LIMIT, path);
+	const userCharLimit = charLimit("userCharLimit", obj.userCharLimit, DEFAULT_USER_CHAR_LIMIT, path);
 
 	return {
 		directory,

package/src/store.ts

@@ -48,9 +48,6 @@ type Result = {
 	writtenEntries?: string[];
 	currentEntries?: string[];
 	matches?: string[];
-	done?: boolean;
-	note?: string;
-	target?: Target;
 };
 
 const PREVIEW_WIDTH = 80;
@@ -68,6 +65,11 @@ function previews(entries: string[]): string[] {
 	return shown;
 }
 
+export function usage(current: number, limit: number): string {
+	const pct = limit > 0 ? Math.min(100, Math.floor((current / limit) * 100)) : 0;
+	return `${pct}% — ${current.toLocaleString()}/${limit.toLocaleString()} chars`;
+}
+
 /**
  * Binding normalization order: strip BOM -> all line terminators to LF -> trim.
  * Delimiter validation, parsing, budgeting, and matching all operate on
@@ -122,34 +124,26 @@ export class MemoryStore {
 	}
 
 	private usage(target: Target): string {
-		const current = this.charCount(target);
-		const limit = this.limit(target);
-		const pct = limit > 0 ? Math.min(100, Math.floor((current / limit) * 100)) : 0;
-		return `${pct}% — ${current.toLocaleString()}/${limit.toLocaleString()} chars`;
+		return usage(this.charCount(target), this.limit(target));
 	}
 
 	private successResponse(target: Target, message?: string, writtenEntries: string[] = []): Result {
 		this.resetOnSuccess();
 		return {
 			success: true,
-			done: true,
-			target,
 			message,
 			usage: this.usage(target),
 			entryCount: this.entries.get(target)!.length,
 			writtenEntries,
-			note: "Write saved. This update is complete — do not repeat it.",
 		};
 	}
 
-	private consolidationFailure(error: string, extra?: Partial<Result>): Result {
-		const target = extra?.target ?? "memory";
+	private consolidationFailure(error: string, target: Target = "memory", resultUsage?: string): Result {
 		return {
 			success: false,
 			error,
 			currentEntries: previews(this.entries.get(target)!),
-			usage: this.usage(target),
-			...extra,
+			usage: resultUsage ?? this.usage(target),
 		};
 	}
 
@@ -404,7 +398,7 @@ export class MemoryStore {
 					+ `Adding this entry (${text.length} chars) would exceed the limit. Consolidate now: use 'replace' to merge `
 					+ `overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), `
 					+ `then retry this add — all in this turn.`,
-				{ target },
+				target,
 			);
 		}
 
@@ -447,7 +441,7 @@ export class MemoryStore {
 		if (resolved[0] === "missing") {
 			return this.consolidationFailure(
 				`No entry matched '${trimmedOld}'. Check current_entries below and retry with the exact text of the entry you want to replace.`,
-				{ target },
+				target,
 			);
 		}
 		if (resolved[0] === "ambiguous") return MemoryStore.ambiguousError(trimmedOld, resolved[1]);
@@ -463,7 +457,7 @@ export class MemoryStore {
 				`Replacement would put memory at ${newTotal.toLocaleString()}/${this.limit(target).toLocaleString()} chars. `
 					+ `Shorten the new content, or 'remove' other stale or less important entries to make room `
 					+ `(see current_entries below), then retry — all in this turn.`,
-				{ target },
+				target,
 			);
 		}
 
@@ -483,7 +477,7 @@ export class MemoryStore {
 		if (resolved[0] === "missing") {
 			return this.consolidationFailure(
 				`No entry matched '${trimmedOld}'. Check current_entries below and retry with the exact text of the entry you want to remove.`,
-				{ target },
+				target,
 			);
 		}
 		if (resolved[0] === "ambiguous") return MemoryStore.ambiguousError(trimmedOld, resolved[1]);
@@ -512,8 +506,9 @@ export class MemoryStore {
 		if (!(await this.reloadTarget(target))) return this.unreadableAbort(target);
 
 		let working = [...this.entries.get(target)!];
+		const writtenEntries = new Set<string>();
 		const fail = (message: string): Result =>
-			this.consolidationFailure(`${message} No operations were applied (batch is all-or-nothing).`, { target });
+			this.consolidationFailure(`${message} No operations were applied (batch is all-or-nothing).`, target);
 
 		for (let i = 0; i < operations.length; i++) {
 			const op = operations[i] ?? {};
@@ -524,8 +519,9 @@ export class MemoryStore {
 
 			if (action === "add") {
 				if (!content) return fail(`${pos}: content is required.`);
-				if (working.includes(normalize(content))) continue; // idempotent duplicate
-				working.push(normalize(content));
+				writtenEntries.add(content);
+				if (working.includes(content)) continue; // idempotent duplicate
+				working.push(content);
 			} else if (action === "replace") {
 				if (!oldText) return fail(`${pos}: old_text is required.`);
 				if (!content) return fail(`${pos}: content is required (use action='remove' to delete).`);
@@ -533,6 +529,7 @@ export class MemoryStore {
 				if (resolved[0] === "missing") return fail(`${pos}: no entry matched '${oldText}'.`);
 				if (resolved[0] === "ambiguous") return fail(`${pos}: '${oldText}' matched multiple distinct entries -- be more specific.`);
 				working[resolved[0]] = content;
+				writtenEntries.add(content);
 				// A replace can create a duplicate; dedupe order-preserving before later ops/budget.
 				working = [...new Set(working)];
 			} else if (action === "remove") {
@@ -553,16 +550,13 @@ export class MemoryStore {
 				`After applying all ${operations.length} operations, memory would be at ${newTotal.toLocaleString()}/`
 					+ `${this.limit(target).toLocaleString()} chars -- over the limit. Remove or shorten more entries in the same batch `
 					+ `(see current_entries below), then retry.`,
-				{ target, usage: `${current.toLocaleString()}/${this.limit(target).toLocaleString()}` },
+				target,
+				`${current.toLocaleString()}/${this.limit(target).toLocaleString()}`,
 			);
 		}
 
 		this.entries.set(target, working);
 		await this.persist(target);
-		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);
+		return this.successResponse(target, `Applied ${operations.length} operation(s).`, [...writtenEntries].filter((entry) => working.includes(entry)));
 	}
 }