@henryqw/pi-memory 0.2.2 → 1.0.1

package/README.md

@@ -28,7 +28,7 @@ To inspect live state, read `<directory>/MEMORY.md`.
 
 ## Config
 
-`~/.pi/agent/config/pi-memory.json`
+`~/.pi/agent/config/pi-memory/config.json`
 
 ```json
 {
@@ -38,7 +38,7 @@ To inspect live state, read `<directory>/MEMORY.md`.
 }
 ```
 
-- `directory`: absolute path where `MEMORY.md` and `USER.md` live. Required only when overriding the default (`~/.pi/agent/memory`). Point it at an iCloud- or Obsidian-synced folder to sync across machines.
+- `directory`: absolute path where `MEMORY.md` and `USER.md` live. Required only when overriding the default (`~/.pi/agent/config/pi-memory/memory`). Point it at an iCloud- or Obsidian-synced folder to sync across machines.
 - `memoryCharLimit` / `userCharLimit`: positive integers, maximum 100000.
 
 Invalid configuration fails fast; malformed config files are never rewritten.
@@ -47,7 +47,7 @@ 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/`.
+Backups and the lock file live outside `directory`, under `~/.pi/agent/config/pi-memory/backups/`.
 
 ## Threat model
 

package/extensions/memory.ts

@@ -5,13 +5,13 @@ import { getAgentDir, withFileMutationQueue, type ExtensionAPI } from "@earendil
 import { Text } from "@earendil-works/pi-tui";
 import { lock } from "proper-lockfile";
 import { Type } from "typebox";
-import { loadMemoryConfig, type MemoryConfig } from "../src/config.ts";
-import { ENTRY_DELIMITER, MemoryStore, type Target } from "../src/store.ts";
+import { configPath, loadMemoryConfig, type MemoryConfig } from "../src/config.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
 // iCloud-synced) so the memory dir holds exactly MEMORY.md and USER.md (ADR 005).
-const BACKUP_DIR = () => join(getAgentDir(), "backups", "pi-memory");
+const BACKUP_DIR = () => join(getAgentDir(), "config", "pi-memory", "backups");
 // 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]";
@@ -87,31 +87,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 {
@@ -229,7 +207,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 {
@@ -271,7 +250,7 @@ export default function memoryExtension(pi: ExtensionAPI): void {
 		// Failed init stays visible every turn (correctness-critical config must
 		// not vanish silently) but as a warning line, not a per-turn throw-loop.
 		if (state.initError) {
-			return { systemPrompt: `${event.systemPrompt}\n\nWARNING: persistent memory is DISABLED this session — initialization failed: ${sanitizeName(state.initError)} Fix config/pi-memory.json and restart.` };
+			return { systemPrompt: `${event.systemPrompt}\n\nWARNING: persistent memory is DISABLED this session — initialization failed: ${sanitizeName(state.initError)} Fix ${configPath()} and restart.` };
 		}
 		if (!state.config || !state.stores || !state.snapshotBlocks) return;
 		const blocks = [...state.snapshotBlocks, ...state.conflictWarnings].filter(Boolean).join("\n\n");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-memory",
-	"version": "0.2.2",
+	"version": "1.0.1",
 	"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

@@ -2,8 +2,9 @@ import { readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-// Repository-mandated single-extension config path boundary (root AGENTS.md).
-export const configPath = () => join(getAgentDir(), "config", "pi-memory.json");
+// Repository-mandated extension config directory boundary (root AGENTS.md):
+// all pi-memory state lives under config/pi-memory/.
+export const configPath = () => join(getAgentDir(), "config", "pi-memory", "config.json");
 
 export interface MemoryConfig {
 	directory: string;
@@ -12,12 +13,20 @@ export interface MemoryConfig {
 }
 
 export function DEFAULT_DIRECTORY(): string {
-	return join(getAgentDir(), "memory");
+	return join(getAgentDir(), "config", "pi-memory", "memory");
 }
 
 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;
@@ -86,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)));
 	}
 }