@henryqw/pi-memory 1.0.1 → 1.1.1

package/README.md

@@ -18,30 +18,26 @@ 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`.
 
 ## Config
 
-`~/.pi/agent/config/pi-memory/config.json`
+Optional JSON file at the exact package-owned path `~/.pi/agent/config/pi-memory/config.json`. All fields are optional; a missing file uses defaults.
 
-```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/config/pi-memory/memory`). Point it at an iCloud- or Obsidian-synced folder to sync across machines.
-- `memoryCharLimit` / `userCharLimit`: positive integers, maximum 100000.
+| Field | Required | Possible values | Default |
+| --- | --- | --- | --- |
+| `directory` | No | Non-empty absolute path without control characters, e.g. an iCloud- or Obsidian-synced folder | `~/.pi/agent/config/pi-memory/memory` |
+| `memoryCharLimit` | No | Safe integer 1–100000 | `8800` |
+| `userCharLimit` | No | Safe integer 1–100000 | `5500` |
 
-Invalid configuration fails fast; malformed config files are never rewritten.
+Any other invalid configuration fails fast: malformed JSON, invalid UTF-8, files over 64 KiB, non-object roots, unknown keys, or out-of-range values throw an error naming the problem; the file is never rewritten.
 
 ## Storage & sync
 
@@ -52,17 +48,3 @@ Backups and the lock file live outside `directory`, under `~/.pi/agent/config/pi
 ## 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

@@ -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.
@@ -101,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;
@@ -254,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.1",
+	"version": "1.1.1",
 	"description": "Auto-managed markdown memory for Pi: capped MEMORY.md/USER.md entry stores with frozen session snapshots.",
 	"keywords": [
 		"pi-package",