@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/memory/README.md

@@ -39,9 +39,15 @@ How the `memory` call and its result look in the transcript — the call line as
 - Re-reads each store when its file changes on disk (compared by mtime and size),
   so an external edit lands in the same session without a restart.
 - Exposes `/memory`: in the TUI it opens a picker to add, edit, or forget a
-  single note, filter by scope, and reload; elsewhere it lists the store.
-  `/memory path`, `edit`, and `clear` print the file paths, open the multi-line
-  editor, and clear a scope.
+  single note, merge two notes into one, move a note to the other scope, filter
+  by scope, and reload; elsewhere it lists the store. `/memory path`, `edit`, and `clear` print the file paths,
+  open the multi-line editor, and clear a scope; `/memory doctor` reports store
+  health.
+- Reports store health with `/memory doctor`: note counts and file bytes per
+  scope, how much of the `maxInjectBytes` budget the injection uses and which
+  scope overflowed it, and the near-duplicate pairs the conservative key already
+  considers one fact. It is read-only — the report names the pair and the picker
+  merges it.
 - Loads and writes the project store only when the project is trusted, sanitizes
   every note to one terminal-safe line, and writes atomically.
 
@@ -91,24 +97,49 @@ or stem both survive.
 
 | Command | What it does |
 |---|---|
-| `/memory` | In the TUI, open the picker (add, edit, or forget a note; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
+| `/memory` | In the TUI, open the picker (add, edit, forget, merge, or move notes; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
 | `/memory list` | Notify the stored notes and counts. |
 | `/memory path` | Notify the two file paths and whether the project store is trusted. |
 | `/memory reload` | Re-read the stores from disk and report what changed. |
+| `/memory doctor` | Report counts, file bytes, the injection budget with the notes it omits, and near-duplicate pairs. Read-only. |
 | `/memory edit [project\|global]` | Open the multi-line editor prefilled with the file and save the result. |
 | `/memory clear [project\|global]` | Clear a scope after a confirmation. |
 
 Bulk deletion lives only in the command, behind a confirm — the model cannot wipe
 memory in one call.
 
+### Picker keys
+
+| Key | Action |
+|---|---|
+| `Enter` / `e` | Edit the focused note in the shared inline editor. |
+| `a` | Add a note to the active scope. |
+| `d` | Forget the focused note after a `y`/`N` confirm. |
+| `m` | Mark the focused note as a merge source; `m` on a second note in the same scope opens the editor pre-filled with `"<first>; <second>"`. `m` on the marked note unmarks it. |
+| `p` | Move the focused note to the other scope: project → global, or global → project. No confirmation; `p` again moves it back, and a move into an untrusted project is refused. |
+| `s` / `Tab` | Cycle the scope filter. |
+| `r` | Re-read the stores. |
+| `Esc` | Cancel the mark, the editor, or the screen, in that order. |
+
+A merge is one write: the store replaces the first note in place and drops the
+second, so a cancelled or failed merge leaves both notes as they were. Two notes
+in different scopes are refused — the stores are separate files.
+
+A move is two writes across those files, ordered target first: the note is added
+to the destination and only then removed from the source. If the second write
+fails the note is in both scopes — a duplicate `/memory doctor` reports and `m`
+merges — rather than gone. A note the destination already holds is not
+duplicated, and the move still removes it from the source.
+
 ## Behaviour by mode
 
 The tool and the context injection work in every mode (`tui`, `rpc`, `json`,
-`print`). The picker opened by a bare `/memory` requires `ctx.mode === "tui"`, and
-`/memory edit` and `/memory clear` require `ctx.hasUI`; in JSON and print sessions
-the command reports that the interactive form needs a TUI session. Memory itself is
-external state, so it is not reconstructed from the session tree and tree
-navigation does not change it.
+`print`), and `/memory doctor` reports through `notify` everywhere. The picker
+opened by a bare `/memory` requires `ctx.mode === "tui"`, and `/memory edit` and
+`/memory clear` require `ctx.hasUI`; in JSON and print sessions the command
+reports that the interactive form needs a TUI session. Memory itself is external
+state, so it is not reconstructed from the session tree and tree navigation does
+not change it.
 
 ## Configuration
 
@@ -152,10 +183,11 @@ skill. Mitigations:
 - The near-duplicate guard on `add` is deliberately conservative: it folds
   case, whitespace runs, and trailing sentence punctuation only, never word
   order, stemming, or internal punctuation. Two paraphrases can therefore still
-  both be stored; use `update` to consolidate them.
+  both be stored; `/memory doctor` reports the pairs the key does consider equal,
+  and `m` in the picker merges them under wording you write.
 - `update` replaces every exact match of `text`; a replacement that already
 exists under a different note can leave a duplicate. Forget the old note first
-when consolidating.
+when consolidating, or merge the pair in the picker afterward.
 - Only one note per line; multi-line notes are collapsed to a single line.
 
 ## Non-goals
@@ -173,13 +205,22 @@ when consolidating.
 |---|---|
 | Registration | The default export registers the `memory` tool, the `/memory` command, and four event listeners; nothing long-lived. |
 | Events | `session_start` loads config and both stores; `before_agent_start` injects the `[MEMORY]` message; `context` keeps only the newest injection; `session_shutdown` clears the cache. The runtime refreshes both stores from their file stamps whenever the notes are read. |
-| Tool | `exposure: "direct"`, `executionMode: "sequential"`, `annotations` and `outputSchema` as above. |
+| Tool | direct exposure (the default), `executionMode: "sequential"`, `annotations` and `outputSchema` as above. |
 | State | External markdown, **not** branch state: the tool result's `details`/`structuredContent` mirror the call but the notes are read from disk and survive independently of `/resume` and `/tree`. |
 | UI | `ctx.ui.notify`, `editor`, and `confirm`, guarded by `ctx.hasUI`, plus the `/memory` picker (`ctx.ui.custom`) in the TUI. |
 | Plan mode | Blocked — `plan`'s read-only policy allows only `readOnlyHint` tools, so memory cannot be mutated while planning; recall still works. |
 
 ## Design notes
 
+- **Health reads the injection it describes.** `injectionPlan` is the same
+  cap arithmetic `buildInjection` joins into the context body, so the doctor
+  cannot claim notes fit while recall drops them; `buildInjection` is a join over
+  that plan, which is why the report needed no second budget model.
+- **A merge is one transform.** `applyMerge` replaces the first note and drops
+  the second inside the same read-modify-write the other mutations use, so a
+  cancelled or failed merge cannot leave one note gone and the other not. The
+  editor is pre-filled with both notes, but the wording saved is the user's — the
+  duplicate rule stays conservative and nothing is folded automatically.
 - **External storage, deliberately.** `goal`/`todo` keep state in tool-result
   `details` because it follows the active branch. Memory is the opposite: it must
   outlive the branch and be editable outside Pi, so it is plain files read at
@@ -207,11 +248,12 @@ when consolidating.
 | `types.ts` | `MemoryScope`, `MemoryAction`, `MemoryDetails`, the context type. |
 | `config.ts` | Defaults and the `memory` section of `bytefly.json` loading/clamping. |
 | `schema.ts` | TypeBox params/result and pure validation of action, scope, and text. |
-| `store.ts` | Paths, parse/read, file stamps, add/update/forget/clear transforms, atomic queued write. |
+| `store.ts` | Paths, parse/read, file stamps, add/update/forget/merge/clear transforms, atomic queued write. |
+| `doctor.ts` | The health report (pure): counts, file bytes, the injection plan's omissions, and near-duplicate pairs. |
 | `runtime.ts` | Session view of both stores, stamp-based refresh, trust gating, mutations. |
 | `format.ts` | Pure call/result/notice text and the bounded injection body. |
 | `errors.ts` | `messageOf`, the shared error-text extraction for the tool and command. |
-| `tui.ts` | The `/memory` picker component (note list, inline editor, scope filter), drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
+| `tui.ts` | The `/memory` picker component (note list, inline editor, merge mark, scope move, scope filter), drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `tools.ts` | `registerTool("memory", …)`. |
 | `commands.ts` | `registerCommand("memory", …)`. |
 

package/extensions/memory/commands.ts

@@ -12,6 +12,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { messageOf } from "./errors.ts";
+import { formatHealth, memoryHealth } from "./doctor.ts";
 import { formatNotice, scopeLabel } from "./format.ts";
 import type { MemoryRuntime } from "./runtime.ts";
 import { MemoryPickerComponent } from "./tui.ts";
@@ -30,10 +31,10 @@ function notify(ctx: ExtensionCommandContext, message: string, kind: "info" | "w
 }
 
 /** `/memory` subcommands and the scope argument accepted by `edit`/`clear`. */
-const MEMORY_SUBCOMMANDS = ["list", "path", "reload", "edit", "clear"];
+const MEMORY_SUBCOMMANDS = ["list", "path", "reload", "doctor", "edit", "clear"];
 
 /** Usage line shared by the command description and the unknown-subcommand warning. */
-const MEMORY_USAGE = "/memory [list | path | reload | edit [project|global] | clear [project|global]]";
+const MEMORY_USAGE = "/memory [list | path | reload | doctor | edit [project|global] | clear [project|global]]";
 
 /** Subcommand on the first token, scope on the second for `edit`/`clear`. */
 function completeMemoryArg(prefix: string): Array<{ value: string; label: string }> | null {
@@ -74,6 +75,8 @@ async function openPicker(pi: ExtensionAPI, runtime: MemoryRuntime, ctx: Extensi
 						add: (scope, text) => runtime.add(scope, text),
 						update: (scope, from, to) => runtime.update(scope, from, to),
 						forget: (scope, entry) => runtime.forget(scope, entry),
+						merge: (scope, first, second, merged) => runtime.merge(scope, first, second, merged),
+						move: (from, to, text) => runtime.move(from, to, text),
 					},
 					() => {
 						stopTimer();
@@ -140,6 +143,21 @@ export function registerCommands(pi: ExtensionAPI, runtime: MemoryRuntime): void
 					);
 					return;
 				}
+				case "doctor": {
+					// Read-only: the report names what to fix, and `m` in the picker merges a pair.
+					notify(
+						ctx,
+						formatHealth(
+							memoryHealth({
+								entries: runtime.entries(),
+								sizes: runtime.sizes(),
+								trusted: runtime.trusted(),
+								config: runtime.config(),
+							}),
+						),
+					);
+					return;
+				}
 				case "edit": {
 					if (!ctx.hasUI) {
 						notify(ctx, "Editing memory requires an interactive session.", "warning");

package/extensions/memory/doctor.ts

@@ -0,0 +1,137 @@
+/**
+ * Memory health: what the two stores hold, and whether recall is already
+ * dropping notes (pure).
+ *
+ * The report answers the questions a user cannot see from the notes alone: how
+ * many notes and bytes each store carries, how much of the `maxInjectBytes`
+ * budget the injection uses and which scope overflowed it, and which notes the
+ * conservative `duplicateKey` already considers the same fact. It never changes
+ * anything — consolidation is the picker's `m` merge, and the doctor only names
+ * the pair to merge.
+ *
+ * Byte counts are the store file's size on disk (what a user can reason about
+ * and compare with the cap), plus the injected body's size; both are exact UTF-8
+ * bytes, not a rounded display.
+ */
+
+import { clip } from "../../lib/tui/columns.ts";
+import type { MemoryConfig } from "./config.ts";
+import { injectionPlan, type MemoryEntries } from "./format.ts";
+import { duplicateKey } from "./store.ts";
+import { MEMORY_SCOPES, type MemoryScope } from "./types.ts";
+
+/** Longest note text a duplicate line shows. */
+const PAIR_NOTE_WIDTH = 60;
+/** Label column for the report's rows. */
+const LABEL_WIDTH = 11;
+
+/** One store's counts. */
+export interface ScopeHealth {
+	notes: number;
+	/** File size in bytes; `undefined` when the store was not read. */
+	bytes?: number;
+}
+
+/** Two notes the comparison key treats as one fact, in stored order. */
+export interface DuplicatePair {
+	scope: MemoryScope;
+	/** The note `add` would have kept. */
+	kept: string;
+	/** The note `add` would have refused as a near-duplicate. */
+	duplicate: string;
+}
+
+export interface MemoryHealth {
+	trusted: boolean;
+	inject: boolean;
+	/** The `maxInjectBytes` cap in effect. */
+	cap: number;
+	project: ScopeHealth;
+	global: ScopeHealth;
+	/** Present while injection is on: the body's bytes and what did not fit. */
+	injection?: { bytes: number; omitted: Record<MemoryScope, number> };
+	duplicates: DuplicatePair[];
+}
+
+export interface HealthInput {
+	entries: MemoryEntries;
+	sizes: Record<MemoryScope, number | undefined>;
+	trusted: boolean;
+	config: MemoryConfig;
+}
+
+/** Every near-duplicate pair, computed with the store's own comparison key. */
+export function duplicatePairs(entries: MemoryEntries): DuplicatePair[] {
+	const pairs: DuplicatePair[] = [];
+	for (const scope of MEMORY_SCOPES) {
+		const kept = new Map<string, string>();
+		for (const note of entries[scope]) {
+			const key = duplicateKey(note);
+			const first = kept.get(key);
+			if (first === undefined) kept.set(key, note);
+			else pairs.push({ scope, kept: first, duplicate: note });
+		}
+	}
+	return pairs;
+}
+
+/** Derive the report from the current stores and config. */
+export function memoryHealth({ entries, sizes, trusted, config }: HealthInput): MemoryHealth {
+	const scope = (name: MemoryScope): ScopeHealth => {
+		const size = sizes[name];
+		return size === undefined ? { notes: entries[name].length } : { notes: entries[name].length, bytes: size };
+	};
+	const plan = config.inject ? injectionPlan(entries, config.maxInjectBytes) : undefined;
+	return {
+		trusted,
+		inject: config.inject,
+		cap: config.maxInjectBytes,
+		project: scope("project"),
+		global: scope("global"),
+		...(plan ? { injection: { bytes: Buffer.byteLength(plan.lines.join("\n"), "utf-8"), omitted: plan.omitted } } : {}),
+		duplicates: duplicatePairs(entries),
+	};
+}
+
+function row(label: string, text: string): string {
+	return `  ${label.padEnd(LABEL_WIDTH)}${text}`;
+}
+
+/** `3 notes · 412 B`, or the reason a store was not read. */
+function scopeText(health: MemoryHealth, name: MemoryScope): string {
+	const scope = health[name];
+	if (name === "project" && !health.trusted) return "unavailable (untrusted project)";
+	const notes = `${scope.notes} note${scope.notes === 1 ? "" : "s"}`;
+	if (scope.bytes === undefined) return scope.notes === 0 ? notes : `${notes} · size unknown`;
+	return `${notes} · ${scope.bytes} B`;
+}
+
+function injectionText(health: MemoryHealth): string {
+	if (!health.inject) return "off (memory.inject is false)";
+	if (!health.injection) return "nothing to inject";
+	const { bytes, omitted } = health.injection;
+	const missing = omitted.project + omitted.global;
+	if (missing === 0) return `${bytes} B of ${health.cap} B · all notes fit`;
+	const scopes = MEMORY_SCOPES.filter((name) => omitted[name] > 0).map((name) => `${name} ${omitted[name]}`);
+	return `${bytes} B of ${health.cap} B · ${missing} omitted (${scopes.join(", ")})`;
+}
+
+function pairLine(pair: DuplicatePair): string {
+	const kept = clip(pair.kept, PAIR_NOTE_WIDTH);
+	const duplicate = clip(pair.duplicate, PAIR_NOTE_WIDTH);
+	return `    ${pair.scope}  "${kept}" ≈ "${duplicate}"`;
+}
+
+/** The `/memory doctor` notice: plain text, one row per fact. */
+export function formatHealth(health: MemoryHealth): string {
+	const count = health.duplicates.length;
+	const duplicates = count === 0 ? "none" : `${count} pair${count === 1 ? "" : "s"} (merge with m in /memory)`;
+	return [
+		"Memory health",
+		row("project", scopeText(health, "project")),
+		row("global", scopeText(health, "global")),
+		row("injection", injectionText(health)),
+		row("duplicates", duplicates),
+		...health.duplicates.map(pairLine),
+	].join("\n");
+}

package/extensions/memory/format.ts

@@ -104,13 +104,21 @@ export function formatNotice(entries: MemoryEntries): string {
 }
 
 /**
- * The hidden `[MEMORY]` context body, or `undefined` when nothing is stored.
+ * The hidden `[MEMORY]` context body split into its lines, plus what did not fit.
  *
  * Sections are emitted project-then-global. When the notes do not fit under
  * `maxBytes`, the remainder is replaced by one `(+N more)` tail so the model
- * knows to call the tool for the rest.
+ * knows to call the tool for the rest. `omitted` says which store overflowed, for
+ * the health report; `buildInjection` only needs the lines.
  */
-export function buildInjection(entries: MemoryEntries, maxBytes: number): string | undefined {
+export interface InjectionPlan {
+	lines: string[];
+	/** Notes that did not fit, per scope. */
+	omitted: Record<MemoryScope, number>;
+}
+
+/** Plan the injected body, or `undefined` when nothing is stored. */
+export function injectionPlan(entries: MemoryEntries, maxBytes: number): InjectionPlan | undefined {
 	const sections: Array<[MemoryScope, string[]]> = [];
 	if (entries.project.length > 0) sections.push(["project", entries.project]);
 	if (entries.global.length > 0) sections.push(["global", entries.global]);
@@ -119,7 +127,7 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 	const lines = [MEMORY_CONTEXT_MARKER, INTRO];
 	let used = lines.reduce((total, line) => total + bytes(line) + 1, 0);
 	const limit = Math.max(0, maxBytes - TAIL_RESERVE);
-	let omitted = 0;
+	const omitted: Record<MemoryScope, number> = { project: 0, global: 0 };
 
 	for (const [scope, list] of sections) {
 		const header = `${scope}:`;
@@ -127,7 +135,7 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 		for (const entry of list) {
 			const line = `- ${entry}`;
 			if (used + bytes(header) + 1 + bytes(line) + 1 > limit) {
-				omitted += 1;
+				omitted[scope] += 1;
 				continue;
 			}
 			rendered.push(line);
@@ -138,6 +146,15 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 			used += bytes(header) + 1;
 		}
 	}
-	if (omitted > 0) lines.push(`- (+${omitted} more; use the memory tool)`);
-	return lines.join("\n");
+	const missing = omitted.project + omitted.global;
+	if (missing > 0) lines.push(`- (+${missing} more; use the memory tool)`);
+	return { lines, omitted };
+}
+
+/**
+ * The hidden `[MEMORY]` context body, or `undefined` when nothing is stored.
+ * Bounded by `maxBytes`, with one tail naming what did not fit.
+ */
+export function buildInjection(entries: MemoryEntries, maxBytes: number): string | undefined {
+	return injectionPlan(entries, maxBytes)?.lines.join("\n");
 }

package/extensions/memory/runtime.ts

@@ -15,6 +15,7 @@ import {
 	applyAdd,
 	applyClear,
 	applyForget,
+	applyMerge,
 	applyUpdate,
 	memoryFileStamp,
 	mutateMemoryFile,
@@ -40,6 +41,13 @@ interface AddResult {
 	existing?: string;
 }
 
+/** Outcome of a scope move: whether the source lost the note, and a target match. */
+export interface MoveResult {
+	moved: boolean;
+	/** The note the target store already had, when it matched as a near-duplicate. */
+	existing?: string;
+}
+
 export interface MemoryRuntime {
 	/** Resolve paths and load notes for a session; returns a warning message, if any. */
 	load(cwd: string, trusted: boolean): Promise<string | undefined>;
@@ -61,6 +69,16 @@ export interface MemoryRuntime {
 	update(scope: MemoryScope, from: string, to: string): Promise<boolean>;
 	forget(scope: MemoryScope, entry: string): Promise<boolean>;
 	clear(scope: MemoryScope): Promise<boolean>;
+	/** File size of each store in bytes; `undefined` when it was not read. */
+	sizes(): Record<MemoryScope, number | undefined>;
+	/** Merge two notes in `scope` into one, in a single write. */
+	merge(scope: MemoryScope, first: string, second: string, merged: string): Promise<boolean>;
+	/**
+	 * Move a note from one scope to the other: written to the target first, then
+	 * removed from the source, so a failure between the two leaves a duplicate
+	 * rather than losing the note.
+	 */
+	move(from: MemoryScope, to: MemoryScope, entry: string): Promise<MoveResult>;
 	/** Drop cached state on shutdown. */
 	reset(): void;
 }
@@ -150,6 +168,14 @@ export function createMemoryRuntime(pi: Pick<ExtensionAPI, "exec">): MemoryRunti
 		},
 		config: () => config,
 		paths: () => paths,
+		sizes: () => {
+			// A store we may not read reports no size, the same way `refresh` refuses
+			// to cache a stamp for it.
+			return {
+				project: trusted ? stampOf("project")?.size : undefined,
+				global: stampOf("global")?.size,
+			};
+		},
 		trusted: () => trusted,
 		entries: () => {
 			refresh();
@@ -188,6 +214,29 @@ export function createMemoryRuntime(pi: Pick<ExtensionAPI, "exec">): MemoryRunti
 			commit(scope, result.entries);
 			return result.changed;
 		},
+		async merge(scope, first, second, merged) {
+			requireTrusted(scope);
+			const result = await mutateMemoryFile(pathFor(scope), (content) => applyMerge(content, first, second, merged));
+			commit(scope, result.entries);
+			return result.changed;
+		},
+		async move(from, to, entry) {
+			if (from === to) throw new Error(`The note is already in ${scopeLabel(from)} memory.`);
+			// Refuse before any write: an untrusted target, or a note that is not in the
+			// source, must leave both stores exactly as they were.
+			requireTrusted(to);
+			// `entries()` refreshes both stores from disk first, so the check is against
+			// what is on disk now, not the cache a previous call left behind.
+			if (!this.entries()[from].includes(entry)) {
+				throw new Error(`No ${scopeLabel(from)} memory note matches "${entry}".`);
+			}
+			// Target first: the one failure possible across two files then leaves the note
+			// in both scopes, where `/memory doctor` reports it and `m` merges it, instead
+			// of deleting the only copy.
+			const added = await this.add(to, entry);
+			const moved = await this.forget(from, entry);
+			return added.existing === undefined ? { moved } : { moved, existing: added.existing };
+		},
 		reset: () => {
 			paths = undefined;
 			config = DEFAULT_MEMORY_CONFIG;

package/extensions/memory/store.ts

@@ -180,6 +180,37 @@ export function applyUpdate(content: string, from: string, to: string): FileChan
 	return changed ? { content: lines.join("\n"), changed: true } : { content, changed: false };
 }
 
+/**
+ * Merge two notes into one: replace `first` in place with `merged` and drop
+ * `second`, so the pair becomes a single bullet where the first one stood. One
+ * transform, so the caller's write is atomic; a missing note or two identical
+ * names changes nothing.
+ */
+export function applyMerge(content: string, first: string, second: string, merged: string): FileChange {
+	if (first === second) return { content, changed: false };
+	const lines = content.split(/\r?\n/);
+	const notes = lines.map((line) => {
+		const match = BULLET_PARTS.exec(line);
+		return match ? sanitizeLine(match[2]) : undefined;
+	});
+	if (!notes.includes(first) || !notes.includes(second)) return { content, changed: false };
+
+	let changed = false;
+	const out: string[] = [];
+	for (const line of lines) {
+		const match = BULLET_PARTS.exec(line);
+		if (match && sanitizeLine(match[2]) === first) {
+			out.push(`${match[1]}${merged}${match[3]}`);
+			changed = true;
+			continue;
+		}
+		if (match && sanitizeLine(match[2]) === second) continue;
+		out.push(line);
+	}
+
+	return changed ? { content: endWithNewline(out.join("\n")), changed: true } : { content, changed: false };
+}
+
 /** Remove every note, keeping the header and any prose. */
 export function applyClear(content: string): FileChange {
 	let changed = false;