@henryqw/pi-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+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,60 @@
+# `@henryqw/pi-memory`
+
+Auto-managed markdown memory for Pi: two size-capped entry stores (`MEMORY.md`, `USER.md`) with a frozen system-prompt snapshot per session.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-memory
+```
+
+## Use
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `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.
+
+To inspect live state, read `<directory>/MEMORY.md`.
+
+## Config
+
+`~/.pi/agent/config/pi-memory.json`
+
+```json
+{
+  "directory": "/absolute/path/to/memory",
+  "memoryCharLimit": 8800,
+  "userCharLimit": 5500
+}
+```
+
+- `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.
+- `memoryCharLimit` / `userCharLimit`: positive integers, maximum 100000.
+
+Invalid configuration fails fast; malformed config files are never rewritten.
+
+## Storage & sync
+
+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.
+
+## 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.
+
+## Remove
+
+```bash
+pi remove npm:@henryqw/pi-memory
+```
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-memory
+npm run typecheck --workspace @henryqw/pi-memory
+npm run pack:check --workspace @henryqw/pi-memory
+```

package/extensions/memory.ts

@@ -0,0 +1,255 @@
+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 { 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";
+
+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");
+// 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]";
+// @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_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.
+
+WHEN: Save proactively when the user states a preference, correction, or personal detail, or you learn a stable fact about their environment, conventions, or workflow. Prioritize user preferences and corrections, then environment facts, then procedures.
+
+IF FULL: Reissue one batch that removes or shortens enough stale entries and adds the new entry together.
+
+TARGETS: user is who the user is (name, role, preferences, style). memory is your notes (environment, conventions, tool quirks, lessons).
+
+EXCLUDE: project- or repository-specific facts (build commands, repo conventions, architecture) do NOT belong here — this store is global across projects; put them in that repository's docs instead.
+
+SKIP: trivial or obvious information, easily rediscovered facts, raw dumps, task progress, completed-work logs, and temporary TODO state. Reusable procedures belong in a skill, not memory.`;
+
+function sanitizeEntry(entry: string): string {
+	return entry.split("\n").map((line) => FRAME_TOKEN_LINE.test(line) ? FRAME_TOKEN_REPLACEMENT : line).join("\n");
+}
+
+// Strip control characters so externally-influenced names can't smuggle
+// prompt structure into warnings.
+function sanitizeName(name: string): string {
+	return name.replace(/[\p{C}]/gu, "").slice(0, 120);
+}
+
+function renderBlock(target: Target, entries: string[], config: MemoryConfig, warnings: string[]): string {
+	if (!entries.length) return "";
+	const limit = target === "user" ? config.userCharLimit : config.memoryCharLimit;
+	// Sanitize BEFORE budgeting: expansion from frame-token replacement must
+	// count against the cap, or many short reserved lines could inflate the
+	// injected snapshot past it.
+	const sanitized = entries.map(sanitizeEntry);
+	// Cap the snapshot at the configured char budget even when the on-disk file
+	// exceeds it (external edit / sync). Omitted entries stay on disk; the
+	// warning tells the model to consolidate before anything new fits.
+	const kept: string[] = [];
+	let used = 0;
+	let omitted = 0;
+	for (const entry of sanitized) {
+		const cost = entry.length + (kept.length ? ENTRY_DELIMITER.length : 0);
+		// No kept.length exemption: a single oversized entry (manual edit or sync)
+		// must be omitted too, or it defeats the advertised context cap.
+		if (used + cost > limit) {
+			omitted = entries.length - kept.length;
+			break;
+		}
+		kept.push(entry);
+		used += cost;
+	}
+	const content = kept.join(ENTRY_DELIMITER);
+	if (content.includes(FRAME_TOKEN_REPLACEMENT)) {
+		warnings.push(`WARNING: frame-token-like lines were filtered out of the ${target} snapshot (see "${FRAME_TOKEN_REPLACEMENT}").`);
+	}
+	if (omitted > 0) {
+		warnings.push(`WARNING: ${target} store is over its character cap; ${omitted} entr${omitted === 1 ? "y was" : "ies were"} omitted from this snapshot. Consolidate stale entries via a memory batch.`);
+	}
+	// 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 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}`;
+}
+
+export default function memoryExtension(pi: ExtensionAPI): void {
+	const state: {
+		config?: MemoryConfig;
+		stores?: Record<Target, MemoryStore>;
+		snapshotBlocks?: string[];
+		conflictWarnings: string[];
+		initError?: string;
+	} = { conflictWarnings: [] };
+
+	pi.on("session_start", async () => {
+		state.config = undefined;
+		state.stores = undefined;
+		state.snapshotBlocks = undefined;
+		state.conflictWarnings = [];
+		state.initError = undefined;
+		try {
+			await mkdir(BACKUP_DIR(), { recursive: true });
+			const config = loadMemoryConfig();
+			await mkdir(config.directory, { recursive: true });
+			// The runtime contract keeps backups OUTSIDE the memory directory; reject
+			// overlap (equal, ancestor, descendant) so backup cleanup can never eat
+			// the store and .bak files can't be mistaken for memory files. Both dirs
+			// exist by now — resolve symlinks and '..' components via realpath.
+			const [realStore, realBackup] = await Promise.all([realpath(config.directory), realpath(BACKUP_DIR())]);
+			if (realStore === realBackup || realStore.startsWith(realBackup + sep) || realBackup.startsWith(realStore + sep)) {
+				throw new Error(`Memory directory must not overlap the backup directory (${BACKUP_DIR()}): got ${config.directory}`);
+			}
+			const backupPath = (target: Target) => join(BACKUP_DIR(), target === "user" ? "USER.md.bak" : "MEMORY.md.bak");
+			const stores: Record<Target, MemoryStore> = {
+				memory: new MemoryStore({ ...config, backupPath }),
+				user: new MemoryStore({ ...config, backupPath }),
+			};
+			const [memory, user, siblings] = await Promise.all([
+				stores.memory.load("memory"),
+				stores.user.load("user"),
+				readdir(config.directory, { withFileTypes: true }),
+			]);
+			const conflictWarnings = [memory.conflictWarning, user.conflictWarning].filter((warning): warning is string => !!warning);
+			// Directory contract is exactly MEMORY.md + USER.md — warn on ANY other
+			// regular file (iCloud conflict copies, stray edits) without guessing its
+			// origin from the name. Bound the list so pointing directory at a large
+			// existing folder can't flood the system prompt.
+			const MAX_LISTED_FILES = 3;
+			const unexpected = siblings.filter((sibling) => sibling.isFile() && sibling.name !== "MEMORY.md" && sibling.name !== "USER.md").map((sibling) => sibling.name).sort();
+			if (unexpected.length > 0) {
+				const listed = unexpected.slice(0, MAX_LISTED_FILES).map((name) => `"${sanitizeName(name)}"`).join(", ");
+				const more = unexpected.length > MAX_LISTED_FILES ? ` and ${unexpected.length - MAX_LISTED_FILES} more` : "";
+				conflictWarnings.push(`WARNING: ${unexpected.length} unexpected file${unexpected.length === 1 ? "" : "s"} in the memory directory (${listed}${more}). Only MEMORY.md and USER.md are loaded; reconcile or remove the rest.`);
+			}
+
+			state.config = config;
+			state.stores = stores;
+			state.snapshotBlocks = [renderBlock("memory", memory.entries, config, conflictWarnings), renderBlock("user", user.entries, config, conflictWarnings)];
+			state.conflictWarnings = conflictWarnings;
+		} catch (error) {
+			// Surface once, disable quietly: no throw-loop every turn.
+			state.initError = error instanceof Error ? error.message : String(error);
+		}
+	});
+
+	// Tool is registered unconditionally at factory time so a failed init
+	// degrades to per-call errors instead of a missing tool.
+	pi.registerTool({
+		name: "memory",
+		label: "Memory",
+		description: `${MEMORY_DESCRIPTION}\n\nTo see current live entries, read MEMORY.md in the configured memory directory with the read tool.`,
+		promptSnippet: "Save durable facts to persistent memory",
+		parameters: Type.Object({
+			action: Type.Optional(StringEnum(["add", "replace", "remove"] as const, {
+				description: "Single change to perform. Omit when using operations.",
+			})),
+			target: Type.Optional(StringEnum(["memory", "user"] as const, {
+				default: "memory",
+				description: "memory for agent notes; user for user profile facts. Defaults to memory.",
+			})),
+			content: Type.Optional(Type.String({ description: "Entry content for add or replace." })),
+			old_text: Type.Optional(Type.String({ description: "Unique substring identifying the entry for replace or remove." })),
+			operations: Type.Optional(Type.Array(Type.Object({
+				action: StringEnum(["add", "replace", "remove"] as const),
+				content: Type.Optional(Type.String()),
+				old_text: Type.Optional(Type.String()),
+			}), { description: "Preferred atomic batch of memory changes." })),
+		}),
+
+		async execute(_toolCallId, params) {
+			if (state.initError) throw new Error(`Memory extension failed to initialize and is disabled: ${state.initError}`);
+			if (!state.config || !state.stores) throw new Error("Memory extension is not initialized.");
+			const target = params.target ?? "memory";
+			const store = state.stores[target];
+			// Serialize the entire mutation window against Pi's edit/write tools.
+			return withFileMutationQueue(join(state.config.directory, target === "user" ? "USER.md" : "MEMORY.md"), async () => {
+				// Recreate before locking: a cleaned-up backup dir would otherwise fail
+				// lock-file creation before persist() gets a chance to restore it.
+				await mkdir(BACKUP_DIR(), { recursive: true });
+				const release = await lock(join(BACKUP_DIR(), ".memory-lock"), {
+					realpath: false,
+					stale: 10_000,
+					retries: { retries: 2, minTimeout: 50, maxTimeout: 200 },
+				});
+				try {
+					let result: Awaited<ReturnType<MemoryStore["add"]>>;
+					if (params.operations !== undefined) result = await store.applyBatch(target, params.operations);
+					else if (params.action === "add") result = await store.add(target, params.content ?? "");
+					else if (params.action === "replace") result = await store.replace(target, params.old_text ?? "", params.content ?? "");
+					else if (params.action === "remove") result = await store.remove(target, params.old_text ?? "");
+					else result = { success: false, error: "Provide action for a single change or operations for a batch." };
+
+					if (!result.success) {
+						let error = result.error ?? "Memory write failed.";
+						// Pi tool errors are plain strings — surface match previews and usage.
+						if (result.matches?.length) error += `\nMatching entries: ${JSON.stringify(result.matches)}`;
+						if (result.usage) error += `\nUsage: ${result.usage}`;
+						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));
+					}
+					store.resetOnSuccess();
+					return {
+						content: [{
+							type: "text" as const,
+							text: JSON.stringify({
+								success: true,
+								done: true,
+								usage: result.usage,
+								entryCount: result.entryCount,
+								message: "Write saved. This update is complete — do not repeat it.",
+							}),
+						}],
+						details: {},
+					};
+				} finally {
+					await release();
+				}
+			});
+		},
+	});
+
+	pi.on("before_agent_start", (event) => {
+		for (const store of Object.values(state.stores ?? {})) store.resetOnSuccess();
+		if (process.argv.includes(BTW_CHILD_PAYLOAD_ARG)) return;
+		// 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.` };
+		}
+		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}` };
+	});
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@henryqw/pi-memory",
+	"version": "0.1.0",
+	"description": "Auto-managed markdown memory for Pi: capped MEMORY.md/USER.md entry stores with frozen session snapshots.",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"memory"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"license": "MIT",
+	"files": [
+		"extensions",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "node --test test/*.test.ts",
+		"typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts src/*.ts test/*.test.ts",
+		"pack:check": "npm pack --dry-run"
+	},
+	"dependencies": {
+		"proper-lockfile": "^4.1.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "^0.84.2",
+		"@earendil-works/pi-coding-agent": "^0.84.2",
+		"typebox": "^1.3.15"
+	},
+	"devDependencies": {
+		"@types/proper-lockfile": "^4.1.4"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/HenryQW/pi-packages.git",
+		"directory": "packages/pi-memory"
+	},
+	"bugs": {
+		"url": "https://github.com/HenryQW/pi-packages/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/memory.ts"
+		]
+	}
+}

package/src/config.ts

@@ -0,0 +1,112 @@
+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");
+
+export interface MemoryConfig {
+	directory: string;
+	memoryCharLimit: number;
+	userCharLimit: number;
+}
+
+export function DEFAULT_DIRECTORY(): string {
+	return join(getAgentDir(), "memory");
+}
+
+export const DEFAULT_MEMORY_CHAR_LIMIT = 8800;
+export const DEFAULT_USER_CHAR_LIMIT = 5500;
+
+export function loadMemoryConfig(explicitPath?: string): MemoryConfig {
+	const path = explicitPath ?? configPath();
+	let raw: string;
+	try {
+		// Bound the read: a config accidentally replaced with (or symlinked to) a
+		// huge file must not exhaust memory before validation. Real configs are
+		// tiny; 64 KiB is generous.
+		const bytes = readFileSync(path);
+		if (bytes.length > 64 * 1024) {
+			throw new Error(`Memory config at ${path} is too large (${bytes.length} bytes); expected < 64 KiB.`);
+		}
+		// Fatal decode: invalid UTF-8 must surface as malformed config, not a
+		// U+FFFD-replaced view that could pass path checks and silently redirect
+		// the memory directory.
+		raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch (error: unknown) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			return {
+				directory: DEFAULT_DIRECTORY(),
+				memoryCharLimit: DEFAULT_MEMORY_CHAR_LIMIT,
+				userCharLimit: DEFAULT_USER_CHAR_LIMIT,
+			};
+		}
+		if (error instanceof TypeError) {
+			throw new Error(`Malformed memory config at ${path}: invalid UTF-8.`);
+		}
+		throw error;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Malformed JSON in memory config at ${path}: ${message}`);
+	}
+
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Memory config at ${path} must be a JSON object.`);
+	}
+
+	const obj = parsed as Record<string, unknown>;
+
+	// Fail fast on typos: an unrecognized key would otherwise silently activate
+	// defaults (e.g. "memoryCharLimits": 100), contradicting the fail-fast contract.
+	const KNOWN_KEYS = ["directory", "memoryCharLimit", "userCharLimit"];
+	for (const key of Object.keys(obj)) {
+		if (!KNOWN_KEYS.includes(key)) {
+			throw new Error(`Unknown key '${key}' in memory config at ${path}. Expected: ${KNOWN_KEYS.join(", ")}.`);
+		}
+	}
+
+	let directory = DEFAULT_DIRECTORY();
+	if (obj.directory !== undefined) {
+		if (typeof obj.directory !== "string" || obj.directory.trim() === "") {
+			throw new Error(`Invalid 'directory' in memory config at ${path}: must be a non-empty string, got ${JSON.stringify(obj.directory)}`);
+		}
+		if (!isAbsolute(obj.directory)) {
+			throw new Error(`Invalid 'directory' in memory config at ${path}: must be an absolute path, got ${JSON.stringify(obj.directory)}`);
+		}
+		// Untrusted config value gets embedded verbatim in prompt warnings;
+		// control characters could forge prompt lines.
+		if (/\p{C}/u.test(obj.directory)) {
+			throw new Error(`Invalid 'directory' in memory config at ${path}: must not contain control characters.`);
+		}
+		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;
+	}
+
+	return {
+		directory,
+		memoryCharLimit,
+		userCharLimit,
+	};
+}

package/src/store.ts

@@ -0,0 +1,562 @@
+import { copyFile, lstat, mkdir, open, rename, stat, writeFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const ENTRY_DELIMITER: string = "\n§\n";
+
+export type Target = "memory" | "user";
+
+export interface StoreConfig {
+	directory: string;
+	memoryCharLimit: number;
+	userCharLimit: number;
+	/** Called before every rewrite of an existing file; store copies the old file there. */
+	backupPath?: (target: Target) => string;
+	/** Test seam: rename implementation. Defaults to fs.rename. */
+	renameFn?: (from: string, to: string) => Promise<void>;
+	/** Test seam: stat implementation for persistence-time checks. Defaults to fs.stat. */
+	statFn?: (path: string) => Promise<import("node:fs").Stats>;
+}
+
+export interface LoadResult {
+	entries: string[];
+	status?: "unreadable" | "oversized";
+	conflictWarning?: string;
+}
+
+export interface BatchOperation {
+	action?: string;
+	content?: string;
+	new_text?: string;
+	old_text?: string;
+}
+
+/** Refuse to inject snapshots above this size into context. */
+export const MAX_FILE_BYTES = 1_000_000;
+
+export type FileState =
+	| { kind: "ok"; raw: string }
+	| { kind: "absent" }
+	| { kind: "unreadable" }
+	| { kind: "oversized"; bytes: number };
+
+type Result = {
+	success: boolean;
+	message?: string;
+	error?: string;
+	usage?: string;
+	entryCount?: number;
+	currentEntries?: string[];
+	matches?: string[];
+	done?: boolean;
+	note?: string;
+	target?: Target;
+};
+
+const PREVIEW_WIDTH = 80;
+const MAX_PREVIEW_ITEMS = 20;
+const MAX_PREVIEW_CHARS = 1500;
+
+function previews(entries: string[]): string[] {
+	let chars = 0;
+	const shown: string[] = [];
+	for (const entry of entries) {
+		if (shown.length >= MAX_PREVIEW_ITEMS || chars + PREVIEW_WIDTH > MAX_PREVIEW_CHARS) break;
+		shown.push(entry.length > PREVIEW_WIDTH ? `${entry.slice(0, PREVIEW_WIDTH)}...` : entry);
+		chars += PREVIEW_WIDTH;
+	}
+	return shown;
+}
+
+/**
+ * Binding normalization order: strip BOM -> all line terminators to LF -> trim.
+ * Delimiter validation, parsing, budgeting, and matching all operate on
+ * normalized text so "a\r\n§\r\nb" cannot smuggle a delimiter past us and
+ * CR/LF/NEL/VT/FF/U+2028/U+2029 cannot smuggle fake frame lines past line-based
+ * filters. ponytail: NFKC/zero-width lookalike spoofing is NOT handled — the
+ * frame headers are advisory context, not a security boundary; revisit only if
+ * entries start coming from untrusted writers.
+ */
+function normalize(raw: string): string {
+	return raw.replace(/^\uFEFF/, "").replace(/\r\n?|[\u2028\u2029\u0085\u000B\u000C]/g, "\n").trim();
+}
+
+function parseEntries(raw: string): string[] {
+	const text = normalize(raw);
+	if (!text) return [];
+	// Deduplicate, preserving order and first occurrence.
+	return [...new Set(text.split(ENTRY_DELIMITER).map((e) => e.trim()).filter(Boolean))];
+}
+
+export class MemoryStore {
+	private readonly config: StoreConfig;
+	private readonly entries = new Map<Target, string[]>([
+		["memory", []],
+		["user", []],
+	]);
+	private consolidationFailures = 0;
+	// Targets whose file was observed on disk this session — used to detect
+	// unexpected mid-session disappearance before a mutation rewrites from an
+	// empty view.
+	private readonly observedExisting = new Set<Target>();
+	private disappearanceDetected = false;
+	private unreadableReason: string | undefined;
+	// mtime/size of the last successfully loaded file, per target.
+	private readonly loadedFingerprints = new Map<Target, { mtimeMs: number; size: number }>();
+
+	constructor(config: StoreConfig) {
+		this.config = config;
+	}
+
+	private limit(target: Target): number {
+		return target === "user" ? this.config.userCharLimit : this.config.memoryCharLimit;
+	}
+
+	private pathFor(target: Target): string {
+		return join(this.config.directory, target === "user" ? "USER.md" : "MEMORY.md");
+	}
+
+	private charCount(target: Target): number {
+		const entries = this.entries.get(target)!;
+		return entries.length ? entries.join(ENTRY_DELIMITER).length : 0;
+	}
+
+	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`;
+	}
+
+	private successResponse(target: Target, message?: string): Result {
+		this.resetOnSuccess();
+		return {
+			success: true,
+			done: true,
+			target,
+			message,
+			usage: this.usage(target),
+			entryCount: this.entries.get(target)!.length,
+			note: "Write saved. This update is complete — do not repeat it.",
+		};
+	}
+
+	private consolidationFailure(error: string, extra?: Partial<Result>): Result {
+		const target = extra?.target ?? "memory";
+		return {
+			success: false,
+			error,
+			currentEntries: previews(this.entries.get(target)!),
+			usage: this.usage(target),
+			...extra,
+		};
+	}
+
+	/**
+	 * Track consecutive consolidation failures. After 3, the model is told to
+	 * stop retrying ({ done: true }); a successful write resets the count.
+	 */
+	incrementFailure(): { done: boolean } {
+		this.consolidationFailures += 1;
+		if (this.consolidationFailures >= 3) {
+			return { done: true };
+		}
+		return { done: false };
+	}
+
+	resetOnSuccess(): void {
+		this.consolidationFailures = 0;
+	}
+
+	async load(target: Target): Promise<LoadResult> {
+		const file = await this.readFileState(target);
+		if (file.kind === "ok") this.observedExisting.add(target);
+		if (file.kind === "unreadable") {
+			return {
+				entries: [],
+				status: "unreadable",
+				conflictWarning: `${this.pathFor(target)} exists but could not be read; refusing to serve a possibly-wrong view.`,
+			};
+		}
+		if (file.kind === "oversized") {
+			return {
+				entries: [],
+				status: "oversized",
+				conflictWarning: `${this.pathFor(target)} is ${file.bytes.toLocaleString()} bytes, over the ${MAX_FILE_BYTES.toLocaleString()}-byte injection limit; refusing to serve it. Consolidate the file manually.`,
+			};
+		}
+		return { entries: file.kind === "ok" ? parseEntries(file.raw) : [] };
+	}
+
+	/**
+	 * Returns file state: "absent" for a missing file, "unreadable" when the file
+	 * EXISTS but could not be read (permissions or invalid UTF-8), "oversized"
+	 * when it exceeds MAX_FILE_BYTES. Callers must abort on unreadable/oversized
+	 * rather than treat it as an empty store.
+	 */
+	private async readFileState(target: Target): Promise<FileState> {
+		// Bounded, EOF-complete read: at most MAX_FILE_BYTES + 1 bytes leave the
+		// filesystem (so a huge synced file can't exhaust memory), and we keep
+		// reading until EOF so a short read from a network/synced filesystem can
+		// never be mistaken for the whole file.
+		let handle: import("node:fs/promises").FileHandle | undefined;
+		try {
+			// Symlinked store files are rejected before anything follows the link:
+			// tmp+rename would replace the link itself and silently disconnect
+			// writes from the intended synced target.
+			const ls = await lstat(this.pathFor(target)).catch(() => null);
+			if (ls?.isSymbolicLink()) {
+				this.unreadableReason = `${this.pathFor(target)} is a symlink; symlinked store files are not supported because atomic rewrites replace the link. Point the memory directory at real files.`;
+				return { kind: "unreadable" };
+			}
+			handle = await open(this.pathFor(target), "r");
+			const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+			let total = 0;
+			for (;;) {
+				if (total > MAX_FILE_BYTES) return { kind: "oversized", bytes: total };
+				const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+				total += bytesRead;
+				if (bytesRead === 0) break; // EOF
+			}
+			// Fatal decode: invalid UTF-8 counts as unreadable — a lossy replacement
+			// view could get persisted back over the real bytes.
+			const raw = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, total));
+			// Fingerprint for the pre-rename change check: an external sync that
+			// lands V2 between this read and persist must not be silently replaced
+			// by V1-plus-mutation.
+			try {
+				const st = await (this.config.statFn ?? stat)(this.pathFor(target));
+				this.loadedFingerprints.set(target, { mtimeMs: st.mtimeMs, size: st.size });
+			} catch {
+				this.loadedFingerprints.delete(target);
+			}
+			return { kind: "ok", raw };
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				// ENOENT on the FILE is "absent" only if the configured directory
+				// itself still exists — a vanished synced/mounted directory must not
+				// be mistaken for an empty store and rewritten divergently.
+				try {
+					await stat(this.config.directory);
+					return { kind: "absent" };
+				} catch {
+					return { kind: "unreadable" };
+				}
+			}
+			return { kind: "unreadable" };
+		} finally {
+			await handle?.close().catch(() => {});
+		}
+	}
+
+	/**
+	 * Re-read from disk into in-memory state. Returns false when the file is
+	 * unreadable or oversized — callers must NOT proceed (never rewrite from an
+	 * assumed-empty view).
+	 */
+	private async reloadTarget(target: Target): Promise<boolean> {
+		const file = await this.readFileState(target);
+		if (file.kind !== "ok" && file.kind !== "absent") return false;
+		if (file.kind === "absent" && this.observedExisting.has(target)) {
+			// The store existed earlier this session and has vanished (sync
+			// conflict, cleanup, accident). Rewriting from the in-memory view would
+			// create a divergent store that hides the original when it reappears.
+			this.disappearanceDetected = true;
+			return false;
+		}
+		if (file.kind === "ok") this.observedExisting.add(target);
+		this.entries.set(target, file.kind === "ok" ? parseEntries(file.raw) : []);
+		return true;
+	}
+
+	private async persist(target: Target): Promise<void> {
+		await mkdir(this.config.directory, { recursive: true });
+		const path = this.pathFor(target);
+		const backup = this.config.backupPath?.(target);
+		if (backup) {
+			// Recreate the backup parent so a cleaned-up backup directory can't be
+			// misread as "source absent" and silently skip the promised backup.
+			await mkdir(dirname(backup), { recursive: true });
+			try {
+				await copyFile(path, backup);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+				// Backup dir now exists, so ENOENT means the SOURCE vanished after
+				// reloadTarget saw it — same divergence hazard as mid-session
+				// disappearance; never proceed from the stale view.
+				if (this.observedExisting.has(target)) {
+					this.disappearanceDetected = true;
+					throw new Error(`${path} vanished before its backup could be written; aborting to avoid a divergent store.`);
+				}
+			}
+		}
+		const content = this.entries.get(target)!.join(ENTRY_DELIMITER);
+		const tmp = join(dirname(path), `.mem_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}`);
+		try {
+			// Preserve restrictive modes/ACLs across inode replacement: default
+			// umask would otherwise turn a 0600 USER.md into 0644.
+			let mode: number | undefined;
+			try {
+				mode = (await stat(path)).mode & 0o777;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			}
+			await writeFile(tmp, content, mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
+			// A creation-assumed write (reload saw the file absent) must not clobber
+			// a file that appeared meanwhile (sync race): re-check just before the
+			// rename, as close to it as possible.
+			if (!this.observedExisting.has(target)) {
+				try {
+					await (this.config.statFn ?? stat)(path);
+					throw new Error(`${path} appeared during this mutation (likely sync); retry to merge its content.`);
+				} catch (error) {
+					if (!(error as NodeJS.ErrnoException).code && (error as Error).message.includes("appeared during")) throw error;
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+					// ENOENT: still absent, proceed.
+				}
+			}
+			// An existing store must not be replaced if the on-disk version changed
+			// since reload (external sync landed V2 after we read V1): compare
+			// fingerprint immediately before the rename.
+			if (this.observedExisting.has(target)) {
+				const fingerprint = this.loadedFingerprints.get(target);
+				if (fingerprint) {
+					const current = await (this.config.statFn ?? stat)(path);
+					if (current.mtimeMs !== fingerprint.mtimeMs || current.size !== fingerprint.size) {
+						throw new Error(`${path} changed during this mutation (likely sync); retry to merge its content.`);
+					}
+				}
+			}
+			await (this.config.renameFn ?? rename)(tmp, path);
+			// The store now exists on disk; a later mid-session disappearance is
+			// unexpected and must abort, not rewrite from the in-memory view.
+			this.observedExisting.add(target);
+		} finally {
+			await rm(tmp, { force: true }).catch(() => {});
+		}
+	}
+
+	private static checkContent(content: string): string | undefined {
+		const normalized = normalize(content);
+		if (!normalized) return "Content cannot be empty.";
+		if (normalized.includes(ENTRY_DELIMITER)) return `Content must not contain the entry delimiter ("${ENTRY_DELIMITER.trim()}”).`;
+		// Same predicate as the snapshot sanitizer (leading Unicode whitespace
+		// included): anything the sanitizer would filter must be rejected here,
+		// or writes report success while vanishing from snapshots.
+		for (const line of normalized.split("\n")) {
+			if (/^\s*(?:═{3,}|MEMORY \(your personal notes|USER PROFILE \(who the user is)/.test(line)) {
+				return "Content must not contain lines starting with '═' separators or the reserved headers 'MEMORY (your personal notes' / 'USER PROFILE (who the user is'.";
+			}
+		}
+		return undefined;
+	}
+
+	private static missingOldTextError(target: Target, action: "replace" | "remove", store: MemoryStore): Result {
+		return {
+			success: false,
+			error: `'${action}' needs old_text -- a short unique substring of the entry to ${action}. None was provided. Reissue the ${action} with old_text set to part of one of the current_entries below.`,
+			currentEntries: previews(store.entries.get(target)!),
+			usage: store.usage(target),
+		};
+	}
+
+	private static ambiguousError(oldText: string, matches: string[]): Result {
+		return {
+			success: false,
+			error: `Multiple entries matched '${oldText}'. Be more specific.`,
+			matches: previews(matches),
+		};
+	}
+
+	/**
+	 * Resolve substring matches against entries. Entries are duplicate-free by
+	 * invariant (dedupe on load + after every mutation), so multiple matches
+	 * are always distinct entries.
+	 */
+	private static resolveMatch(entries: string[], oldText: string): ["missing"] | ["ambiguous", string[]] | [number] {
+		const matches = entries.map((e, i) => (e.includes(oldText) ? i : -1)).filter((i) => i >= 0);
+		if (matches.length === 0) return ["missing"];
+		if (matches.length > 1) {
+			return ["ambiguous", matches.map((i) => entries[i])];
+		}
+		return [matches[0]];
+	}
+
+	async add(target: Target, content: string): Promise<Result> {
+		const contentError = MemoryStore.checkContent(content);
+		if (contentError) return { success: false, error: contentError };
+		const text = normalize(content);
+
+		if (!(await this.reloadTarget(target))) {
+			return this.unreadableAbort(target);
+		}
+		const entries = this.entries.get(target)!;
+
+		if (entries.includes(text)) {
+			return this.successResponse(target, "Entry already exists (no duplicate added).");
+		}
+
+		const newTotal = [...entries, text].join(ENTRY_DELIMITER).length;
+		if (newTotal > this.limit(target)) {
+			return this.consolidationFailure(
+				`Memory at ${this.charCount(target).toLocaleString()}/${this.limit(target).toLocaleString()} chars. `
+					+ `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 },
+			);
+		}
+
+		entries.push(text);
+		await this.persist(target);
+		return this.successResponse(target, "Entry added.");
+	}
+
+	private unreadableAbort(target: Target): Result {
+		if (this.unreadableReason) {
+			const reason = this.unreadableReason;
+			this.unreadableReason = undefined;
+			return { success: false, error: reason };
+		}
+		if (this.disappearanceDetected) {
+			this.disappearanceDetected = false;
+			return {
+				success: false,
+				error: `${this.pathFor(target)} existed earlier this session but has disappeared (sync conflict, cleanup, or accident). Writing now would create a divergent store that hides the original when it returns. Restore the file (with the entries you want to keep) — once recreated, mutations work normally again.`,
+			};
+		}
+		return {
+			success: false,
+			error: `${this.pathFor(target)} exists but could not be read (unreadable, or over the ${MAX_FILE_BYTES.toLocaleString()}-byte limit). The on-disk entries are unknown, so writing would `
+				+ `risk wiping them. Fix the file and retry — nothing was changed.`,
+		};
+	}
+
+	async replace(target: Target, oldText: string, newText: string): Promise<Result> {
+		const contentError = MemoryStore.checkContent(newText);
+		if (contentError) return { success: false, error: contentError };
+
+		// Reload before validating old_text so failure results reflect DISK state.
+		if (!(await this.reloadTarget(target))) return this.unreadableAbort(target);
+		const trimmedOld = normalize(oldText ?? "");
+		if (!trimmedOld) return MemoryStore.missingOldTextError(target, "replace", this);
+		const entries = this.entries.get(target)!;
+
+		const resolved = MemoryStore.resolveMatch(entries, trimmedOld);
+		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 },
+			);
+		}
+		if (resolved[0] === "ambiguous") return MemoryStore.ambiguousError(trimmedOld, resolved[1]);
+
+		const text = normalize(newText);
+		const testEntries = [...entries];
+		testEntries[resolved[0]] = text;
+		// A replace can create a duplicate; dedupe order-preserving before budget.
+		const deduped = [...new Set(testEntries)];
+		const newTotal = deduped.join(ENTRY_DELIMITER).length;
+		if (newTotal > this.limit(target)) {
+			return this.consolidationFailure(
+				`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 },
+			);
+		}
+
+		this.entries.set(target, deduped);
+		await this.persist(target);
+		return this.successResponse(target, "Entry replaced.");
+	}
+
+	async remove(target: Target, oldText: string): Promise<Result> {
+		// Reload before validating old_text so failure results reflect DISK state.
+		if (!(await this.reloadTarget(target))) return this.unreadableAbort(target);
+		const trimmedOld = normalize(oldText ?? "");
+		if (!trimmedOld) return MemoryStore.missingOldTextError(target, "remove", this);
+		const entries = this.entries.get(target)!;
+
+		const resolved = MemoryStore.resolveMatch(entries, trimmedOld);
+		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 },
+			);
+		}
+		if (resolved[0] === "ambiguous") return MemoryStore.ambiguousError(trimmedOld, resolved[1]);
+
+		entries.splice(resolved[0], 1);
+		await this.persist(target);
+		return this.successResponse(target, "Entry removed.");
+	}
+
+	/**
+	 * Apply add/replace/remove operations atomically against the FINAL budget:
+	 * intermediate overflow is fine, only the end state is checked. All-or-nothing.
+	 */
+	async applyBatch(target: Target, operations: BatchOperation[]): Promise<Result> {
+		if (!operations || operations.length === 0) {
+			return { success: false, error: "operations list is empty." };
+		}
+		for (const op of operations) {
+			const content = op.content ?? op.new_text ?? "";
+			if ((op.action === "add" || op.action === "replace") && content) {
+				const contentError = MemoryStore.checkContent(content);
+				if (contentError) return { success: false, error: contentError };
+			}
+		}
+
+		if (!(await this.reloadTarget(target))) return this.unreadableAbort(target);
+
+		let working = [...this.entries.get(target)!];
+		const fail = (message: string): Result =>
+			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] ?? {};
+			const action = op.action;
+			const content = normalize(op.content ?? op.new_text ?? "");
+			const oldText = normalize(op.old_text ?? "");
+			const pos = `Operation ${i + 1} (${action ?? "unknown"})`;
+
+			if (action === "add") {
+				if (!content) return fail(`${pos}: content is required.`);
+				if (working.includes(normalize(content))) continue; // idempotent duplicate
+				working.push(normalize(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).`);
+				const resolved = MemoryStore.resolveMatch(working, oldText);
+				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;
+				// A replace can create a duplicate; dedupe order-preserving before later ops/budget.
+				working = [...new Set(working)];
+			} else if (action === "remove") {
+				if (!oldText) return fail(`${pos}: old_text is required.`);
+				const resolved = MemoryStore.resolveMatch(working, oldText);
+				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.splice(resolved[0], 1);
+			} else {
+				return fail(`${pos}: unknown action. Use add, replace, or remove.`);
+			}
+		}
+
+		const newTotal = working.length ? working.join(ENTRY_DELIMITER).length : 0;
+		if (newTotal > this.limit(target)) {
+			const current = this.charCount(target);
+			return this.consolidationFailure(
+				`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()}` },
+			);
+		}
+
+		this.entries.set(target, working);
+		await this.persist(target);
+		return this.successResponse(target, `Applied ${operations.length} operation(s).`);
+	}
+}