@astrosheep/pi-context 0.20.0 → 0.22.0

package/src/{memory → notes}/paths.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export type Scope = "session" | "project" | "global";
+export type Scope = "session" | "project" | "personal";
 
 /** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
 export function notesRoot(): string {
@@ -12,6 +12,11 @@ export function notesRoot(): string {
 	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
 }
 
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home = notesRoot()): string {
+	return join(home, "pi", "session");
+}
+
 /**
  * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
  * No git root yields undefined, which projectKey then replaces with the cwd itself.
@@ -41,9 +46,9 @@ function sessionId(ctx: ExtensionContext): string {
 
 /** Absolute directory holding every note of one scope. */
 export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
-	if (scope === "global") return join(notesRoot(), "global");
+	if (scope === "personal") return join(notesRoot(), "personal");
 	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
-	return join(notesRoot(), "pi", "session", sessionId(ctx));
+	return join(sessionHomesRoot(), sessionId(ctx));
 }
 
 /**

package/src/{memory → notes}/store.ts

@@ -3,10 +3,12 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, w
 import { dirname } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { generateDiffString } from "@earendil-works/pi-coding-agent";
-import { assertGlobPattern, assertVirtualPath, globToRegExp } from "../notes.js";
+import { assertGlobPattern, assertVirtualPath, globToRegExp } from "./model.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
 import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { addressFor } from "./address.js";
 import { physicalPath, scopeDir, type Scope } from "./paths.js";
+import { earliestMatchOffsetChars } from "../tool-output.js";
 
 export type { NoteMeta, Origin, Scope };
 
@@ -26,14 +28,14 @@ export class NoteError extends Error {
 	}
 }
 
-export type NoteRow = { path: string; meta: NoteMeta; sizeBytes: number };
+export type NoteRow = { address: string; scope: Scope; path: string; meta: NoteMeta; body: string; sizeBytes: number };
 export type NoteMatch = { line: number; text: string; offsetChars: number };
-export type NoteSearchRow = { path: string; scope: Scope; meta: NoteMeta; matches: NoteMatch[] };
+export type NoteSearchRow = { address: string; scope: Scope; path: string; meta: NoteMeta; matches: NoteMatch[] };
 
-const SCOPE_ORDER: readonly Scope[] = ["session", "project", "global"];
+const SCOPE_ORDER: readonly Scope[] = ["session", "project", "personal"];
 
 function assertScope(value: unknown): Scope {
-	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, global (got ${JSON.stringify(value)})`);
+	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, personal (got ${JSON.stringify(value)})`);
 	return value;
 }
 
@@ -42,22 +44,6 @@ function assertOrigin(value: unknown): Origin {
 	return value;
 }
 
-function scopeList(scope?: unknown): Scope[] {
-	if (scope === undefined || scope === null) return [...SCOPE_ORDER];
-	return [assertScope(scope)];
-}
-
-type Resolved = { scope: Scope; path: string; raw: string };
-
-/** First existing file by precedence session → project → global, or only `scope` when given. */
-function resolve(ctx: ExtensionContext, vpath: string, scope?: unknown): Resolved | undefined {
-	for (const candidate of scopeList(scope)) {
-		const path = physicalPath(candidate, vpath, ctx);
-		if (existsSync(path)) return { scope: candidate, path, raw: readFileSync(path, "utf8") };
-	}
-	return undefined;
-}
-
 /** Recursively list `.md` files under `dir` as forward-slash virtual paths relative to `base`. */
 function walkMarkdown(dir: string, base = dir): string[] {
 	let entries: Dirent[];
@@ -160,7 +146,7 @@ export function writeNote(ctx: ExtensionContext, vpath: string, body: string, op
 }
 
 export type EditOperation = { oldText: string; newText: string };
-export type EditOptions = { scope?: Scope; origin?: Origin; stale?: boolean; replaceAll?: boolean };
+export type EditOptions = { origin?: Origin; stale?: boolean; replaceAll?: boolean };
 
 /** Dream harness mutation: metadata changes still use the store's atomic writer. */
 export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scope, mutate: (meta: NoteMeta) => void): { meta: NoteMeta; body: string } {
@@ -177,17 +163,19 @@ export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scop
 	return { meta, body: parsed.body };
 }
 
-/** Apply body-only edits against one snapshot, then optionally move via the scope/origin/stale setters. */
-export function editNote(ctx: ExtensionContext, vpath: string, edits: EditOperation[] | undefined, opts: EditOptions = {}): { meta: NoteMeta; applied: number; resolved_scope: Scope; diff: string } {
+/** Apply body-only edits against one explicit home; origin and stale are its metadata setters. */
+export function editNote(ctx: ExtensionContext, vpath: string, scope: Scope, edits: EditOperation[] | undefined, opts: EditOptions = {}): { meta: NoteMeta; applied: number; resolved_scope: Scope; diff: string } {
 	assertVirtualPath(vpath);
 	assertWritablePath(vpath);
 	const operations = edits ?? [];
-	if (operations.length === 0 && opts.scope === undefined && opts.origin === undefined && opts.stale === undefined) {
-		throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of scope, origin, stale");
+	if (operations.length === 0 && opts.origin === undefined && opts.stale === undefined) {
+		throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
 	}
-	const found = resolve(ctx, vpath);
-	if (!found) throw new NoteError("not_found", "note not found");
-	const { meta, body } = parseNote(found.raw);
+	const path = physicalPath(scope, vpath, ctx);
+	if (!existsSync(path)) throw new NoteError("not_found", "note not found");
+	const raw = readFileSync(path, "utf8");
+	const { meta, body } = parseNote(raw);
+	meta.scope = scope;
 	// Snapshot the pre-edit frontmatter so the diff can name exactly what the setters changed.
 	const beforeMeta: NoteMeta = { ...meta };
 	// Every edit runs against this one snapshot; nothing is written until all of them succeed,
@@ -203,79 +191,65 @@ export function editNote(ctx: ExtensionContext, vpath: string, edits: EditOperat
 		if (lines.length > 1 && !opts.replaceAll) {
 			throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
 		}
-		next = opts.replaceAll ? next.split(oldText).join(newText) : next.replace(oldText, newText);
+		// Single replacement is positional splicing, never String.replace: user text must be
+		// inserted byte-for-byte, without $-pattern substitution ($&, $`, $', $1, $$).
+		if (opts.replaceAll) {
+			next = next.split(oldText).join(newText);
+		} else {
+			const matchIndex = next.indexOf(oldText);
+			next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+		}
 	});
-	const destScope = opts.scope === undefined ? found.scope : assertScope(opts.scope);
 	if (opts.origin !== undefined) meta.origin = assertOrigin(opts.origin);
 	if (opts.stale !== undefined) meta.stale = opts.stale;
-	meta.scope = destScope;
 	meta.updated_at = Date.now();
-	const dest = physicalPath(destScope, vpath, ctx);
-	const moving = dest !== found.path;
-	if (moving && existsSync(dest)) {
-		throw new NoteError("target_exists", `a note already exists at ${vpath} in scope ${destScope}; the move was refused and both files are unchanged`);
-	}
 	const serialized = serializeNote(meta, next);
 	assertSerializedSize(serialized);
 	// pi-edit-style diff: body only for a content edit, frontmatter only for a metadata-only
-	// update, one combined file diff when both moved.
+	// update, one combined file diff when both change.
 	const bodyChanged = body !== next;
-	const metadataChanged = beforeMeta.scope !== meta.scope || beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+	const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
 	const diff = bodyChanged && metadataChanged
-		? generateDiffString(found.raw, serialized).diff
+		? generateDiffString(raw, serialized).diff
 		: bodyChanged
 			? generateDiffString(body, next).diff
 			: metadataChanged
 				? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff
 				: "";
-	atomicWrite(dest, serialized);
-	if (moving) rmSync(found.path);
-	return { meta, applied: operations.length, resolved_scope: found.scope, diff };
+	atomicWrite(path, serialized);
+	return { meta, applied: operations.length, resolved_scope: scope, diff };
 }
 
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx: ExtensionContext, vpath: string, opts: { scope?: Scope } = {}): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
+export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
 	assertVirtualPath(vpath);
-	const found = resolve(ctx, vpath, opts.scope);
-	if (!found) return undefined;
+	const path = physicalPath(scope, vpath, ctx);
+	if (!existsSync(path)) return undefined;
 	const now = Date.now();
-	const { meta, body } = parseNote(found.raw, now);
-	meta.scope = found.scope;
+	const { meta, body } = parseNote(readFileSync(path, "utf8"), now);
+	meta.scope = scope;
 	// Only the two access keys move; updated_at and every other key keep their bytes.
 	meta.last_accessed = now;
 	meta.access_count = (typeof meta.access_count === "number" ? meta.access_count : 0) + 1;
-	atomicWrite(found.path, serializeNote(meta, body));
-	return { meta, body, resolvedScope: found.scope };
-}
-
-/** The scope that holds `vpath` first by precedence, without reading or mutating the file. */
-export function resolveNoteScope(ctx: ExtensionContext, vpath: string, scope?: Scope): { scope: Scope; path: string } | undefined {
-	const found = resolve(ctx, vpath, scope);
-	return found ? { scope: found.scope, path: found.path } : undefined;
-}
-
-/** Read a note's meta and body without the read side effect (used by the boot index). */
-export function peekNote(ctx: ExtensionContext, scope: Scope, vpath: string): { meta: NoteMeta; body: string } {
-	const path = physicalPath(scope, vpath, ctx);
-	const { meta, body } = parseNote(readFileSync(path, "utf8"));
-	meta.scope = scope;
-	return { meta, body };
+	atomicWrite(path, serializeNote(meta, body));
+	return { meta, body, resolvedScope: scope };
 }
 
-/** Merged rows across scopes, most recently updated first (path then scope break ties). */
+/** Merged rows across homes, most recently updated first (address breaks ties). */
 export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; pattern?: string } = {}): NoteRow[] {
 	const matcher = matcherFor(opts.pattern);
 	const rows: NoteRow[] = [];
-	for (const scope of scopeList(opts.scope)) {
+	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
 		const root = scopeDir(scope, ctx);
 		for (const path of walkMarkdown(root)) {
-			if (matcher && !matcher.test(path)) continue;
+			const address = addressFor(scope, path);
+			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
-			rows.push({ path, meta, sizeBytes: Buffer.byteLength(body, "utf8") });
+			rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
 		}
 	}
-	rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.path.localeCompare(b.path) || a.meta.scope.localeCompare(b.meta.scope));
+	rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
 	return rows;
 }
 
@@ -283,28 +257,24 @@ export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; pattern?
 export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { scope?: Scope; pattern?: string } = {}): NoteSearchRow[] {
 	const matcher = matcherFor(opts.pattern);
 	const rows: NoteSearchRow[] = [];
-	for (const scope of scopeList(opts.scope)) {
+	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
 		const root = scopeDir(scope, ctx);
 		for (const path of walkMarkdown(root)) {
-			if (matcher && !matcher.test(path)) continue;
+			const address = addressFor(scope, path);
+			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
 			let baseChars = 0;
 			const matches: NoteMatch[] = [];
 			for (const [index, line] of body.split("\n").entries()) {
 				if (queries.some((query) => line.includes(query))) {
-					let earliest = -1;
-					for (const query of queries) {
-						const found = line.indexOf(query);
-						if (found >= 0 && (earliest < 0 || found < earliest)) earliest = found;
-					}
-					matches.push({ line: index + 1, text: line, offsetChars: baseChars + (earliest <= 0 ? 0 : Array.from(line.slice(0, earliest)).length) });
+					matches.push({ line: index + 1, text: line, offsetChars: baseChars + earliestMatchOffsetChars(line, queries) });
 				}
 				baseChars += Array.from(line).length + 1;
 			}
-			if (matches.length > 0) rows.push({ path, scope, meta, matches });
+			if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
 		}
 	}
-	rows.sort((a, b) => a.path.localeCompare(b.path) || a.scope.localeCompare(b.scope));
+	rows.sort((a, b) => a.address.localeCompare(b.address));
 	return rows;
 }

package/src/notes/tools.ts

@@ -0,0 +1,132 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { localIso } from "./model.js";
+import { characterWindowHeader, DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
+import { assertAddress } from "./address.js";
+import { serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+
+const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
+	description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else — third-party text, tool output, fetched material.",
+}));
+const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project's home, and `@personal/<vpath>` for the human's cross-project home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@personal/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
+
+function wireMeta(meta: NoteMeta): Record<string, unknown> {
+	return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
+}
+
+function failure(error: unknown) {
+	if (error instanceof NoteError) {
+		const payload: Record<string, unknown> = { error: error.message };
+		if (error.line_numbers) payload.line_numbers = error.line_numbers;
+		if (error.edit_index !== undefined) payload.edit_index = error.edit_index;
+		return output(payload);
+	}
+	throw error;
+}
+
+export function registerNotesTools(pi: ExtensionAPI) {
+	pi.registerTool(defineTool({
+		name: "notes_write", label: "Notes write",
+		description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} Keep notes small and split by topic — by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving created_at and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
+		parameters: Type.Object({ address: Type.String(), content: Type.String(), origin: ORIGIN, stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			const content = params.content;
+			try {
+				const destination = assertAddress(params.address);
+				const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				return output({ address: params.address, scope: meta.scope, size_bytes: Buffer.byteLength(stripLeadingFrontmatter(content), "utf8"), meta: wireMeta(meta) });
+			} catch (error) { return failure(error); }
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_edit", label: "Notes edit",
+		description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries resolved_scope and a diff of what changed.`,
+		parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			try {
+				const destination = assertAddress(params.address);
+				const { meta, applied, resolved_scope, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				return output({ address: params.address, applied, resolved_scope, diff, meta: wireMeta(meta) });
+			} catch (error) { return failure(error); }
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_read", label: "Notes read",
+		description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw frontmatter + body behind a one-line [bracketed] header naming the address, the resolved offset, the delivered char range, and the resume cursor.`,
+		parameters: Type.Object({ address: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })) }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			let note: ReturnType<typeof readNote>;
+			try {
+				const destination = assertAddress(params.address);
+				note = readNote(ctx, destination.path, destination.scope);
+			} catch (error) { return failure(error); }
+			if (!note) return output({ error: "note not found", address: params.address });
+			const text = serializeNote(note.meta, note.body);
+			const totalChars = Array.from(text).length;
+			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, address: params.address, offset_chars: params.offset_chars, total_chars: totalChars });
+			const created_at = localIso(note.meta.created_at);
+			const updated_at = localIso(note.meta.updated_at);
+			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
+			return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...rest } = window;
+				return outputRaw(characterWindowHeader(params.address, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { address: params.address, scope: note.resolvedScope, ...rest, limit_chars, created_at, updated_at });
+			}, (result) => withinTextBudget(result.content[0].text));
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_list", label: "Notes list",
+		description: `List note files as rows carrying address, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
+		parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			let rows: ReturnType<typeof listNotes>;
+			try { rows = listNotes(ctx, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
+			const files: Array<{ address: string; scope: string; origin: Origin; status: string; stale: boolean; size_bytes: number; created_at: string; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, scope: row.scope, origin: row.meta.origin, status: row.meta.status, stale: row.meta.stale, size_bytes: row.sizeBytes, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at) }));
+			return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+				if (fits(file)) return file;
+				const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
+				return { ...file, address, address_truncated: true };
+			}));
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_search", label: "Notes search",
+		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} All three homes are merged and every entry carries its full address and derived scope. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (the body-absolute code-point offset of the earliest match).`,
+		parameters: Type.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const queries = searchQueries(params.query);
+			let rows: ReturnType<typeof searchNotes>;
+			try { rows = searchNotes(ctx, queries, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
+			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+			const result: Array<{ address: string; scope: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
+				const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, total_chars: Array.from(match.text).length, offset_chars: match.offsetChars }));
+				return { address: row.address, scope: row.scope, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at), matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+			});
+			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
+				if (fits(file)) return file;
+				const matches = file.matches;
+				let low = 0;
+				let high = matches.length;
+				while (low < high) {
+					const mid = Math.ceil((low + high) / 2);
+					if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) })) low = mid;
+					else high = mid - 1;
+				}
+				if (low >= 1) return { ...file, matches: matches.slice(0, low) };
+				const first = matches[0]!;
+				const fitted = (text: string): (typeof result)[number] => ({ ...file, matches: [{ ...first, text, truncated: true }] });
+				const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+				const prefix = fitted(text);
+				if (fits(prefix)) return prefix;
+				const address = middleTruncate(prefix.address, (candidate) => fits({ ...prefix, address: candidate, address_truncated: true }));
+				return { ...prefix, address, address_truncated: true };
+			};
+			return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+		},
+	}));
+}

package/src/prompts.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { historyFromSession } from "./history.js";
-import { localIso } from "./notes.js";
-import { listNotes, peekNote, resolveNoteScope } from "./memory/store.js";
-import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, NOTE_PREVIEW_CHARS, NOTE_PREVIEW_HEAD_CHARS, NOTE_PREVIEW_TAIL_CHARS, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
+import { listNotes } from "./notes/store.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_PERSONAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
 
 /** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
 function identityBlock(agentName: string, firstWindowId: string, currentWindowId: string, previousWindowId?: string): string {
@@ -15,44 +14,55 @@ function identityBlock(agentName: string, firstWindowId: string, currentWindowId
 	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
 }
 
+function relativeTime(timestamp: number, now: number): string {
+	const seconds = Math.trunc((timestamp - now) / 1000);
+	const [unit, size] = ([["d", 86400], ["h", 3600], ["m", 60], ["s", 1]] as const)
+		.find(([unit, size]) => Math.abs(seconds) >= size || unit === "s")!;
+	const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
+	return seconds > 0 ? `in ${amount}` : `${amount} ago`;
+}
+
 /**
- * Recent-notes index: up to three most-recent fresh (non-stale) notes. Each note shows its
- * path, line count, UTF-8 byte count and local ISO update time, followed by an indented inline
- * preview: the whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first
- * NOTE_PREVIEW_HEAD_CHARS and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an
- * explicit ellipsis. The two slices never overlap, so the preview never duplicates head content
- * as tail content. Stale notes are excluded entirely; empty when no fresh notes remain.
+ * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the personal and
+ * project homes are both injected, broadest first; stale maps are skipped per home, and the
+ * session home is never peeked — a session MAP.md is an ordinary note. The pocket then lists
+ * recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT / POCKET_PROJECT_LIMIT /
+ * POCKET_PERSONAL_LIMIT), most-recently-updated first within each home, one metadata line
+ * each: address, line count, UTF-8 byte count, relative update time at window open. Bodies never render
+ * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
  */
 function notesIndex(ctx: ExtensionContext): string {
 	const sections: string[] = [];
-	// TOC residency ("地图在场"): the map, when present, is injected whole ahead of the list.
-	const toc = resolveNoteScope(ctx, "TOC.md");
-	if (toc) {
-		const body = peekNote(ctx, toc.scope, "TOC.md").body;
-		if (body.length > 0) sections.push(body);
+	// Map residency ("地图在场"): scope-native maps, both fresh ones injected broadest-first.
+	// A session MAP.md is an ordinary note, never resident; stale maps skip independently.
+	for (const scope of ["personal", "project"] as const) {
+		const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
+		if (toc && !toc.meta.stale) {
+			if (toc.body.length > 0) sections.push(toc.body);
+		}
 	}
-	// listNotes is already most-recently-updated first; stale notes never reach the index.
-	const recentNotes = listNotes(ctx, {})
-		.filter((row) => !row.meta.stale)
-		.slice(0, 5);
+	// listNotes is most-recently-updated first within each home. Per-home quotas keep session
+	// churn from evicting project or personal notes; maps never take pocket seats.
+	const recentNotes = [
+		...listNotes(ctx, { scope: "session" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
+		...listNotes(ctx, { scope: "project" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
+		...listNotes(ctx, { scope: "personal" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PERSONAL_LIMIT),
+	];
 	if (recentNotes.length > 0) {
-		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (up to 5, most recent first):`];
+		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_PERSONAL_LIMIT} from personal). A note's content never appears here, so its name has to say what the note is about:`];
+		const now = Date.now();
 		for (const row of recentNotes) {
-			const body = peekNote(ctx, row.meta.scope, row.path).body;
-			lines.push(`- ${row.path} (${body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${localIso(row.meta.updated_at)})`);
-			const chars = Array.from(body);
-			// Short notes stay whole; long notes keep both ends. head + tail <= NOTE_PREVIEW_CHARS < chars.length,
-			// so the slices are disjoint and no character is shown twice.
-			const preview = chars.length <= NOTE_PREVIEW_CHARS
-				? body
-				: `${chars.slice(0, NOTE_PREVIEW_HEAD_CHARS).join("")}…${chars.slice(chars.length - NOTE_PREVIEW_TAIL_CHARS).join("")}`;
-			lines.push(preview.split("\n").map((line) => `  ${line}`).join("\n"));
+			lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, now)})`);
 		}
 		sections.push(lines.join("\n"));
 	}
 	return sections.join("\n\n");
 }
 
+function notesHomeBlock(): string {
+	return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @personal/<vpath> is the human's cross-project home. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
+}
+
 /**
  * Assemble the static, once-per-window boot block: the reset line for resets, the
  * <context_window> identity block, the recent-notes index at window-open time, and
@@ -64,6 +74,7 @@ export function bootBlock(ctx: ExtensionContext, currentId: string, previousId:
 	const parts: string[] = [];
 	if (resetLine) parts.push(RESET_SUMMARY);
 	parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
+	parts.push(notesHomeBlock());
 	const index = notesIndex(ctx);
 	if (index) parts.push(index);
 	parts.push(PROTOCOL_BLOCK);
@@ -78,4 +89,3 @@ export function bootBlock(ctx: ExtensionContext, currentId: string, previousId:
 export function tokenBudgetGuidance(remaining: number): string {
 	return `${GUIDANCE_OPEN_TAG}\nYour brain is almost out of room — ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now — the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Replacing an older checkpoint? Mark it stale. Then end the window yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
 }
-

package/src/protocol.ts

@@ -7,6 +7,9 @@ export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
 export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
+export const POCKET_SESSION_LIMIT = 5;
+export const POCKET_PROJECT_LIMIT = 2;
+export const POCKET_PERSONAL_LIMIT = 2;
 // Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
 // notesFromSession replays already-persisted operations, which must keep loading sessions
 // that contain a longer legacy path. Reads and replay stay un-capped.
@@ -18,6 +21,8 @@ export const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
 export const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
 export const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
 export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+/** Nested under "pi-context": the default dreamer model pattern, overridden by CLI --dreamer. */
+export const PI_CONTEXT_DREAMER_KEY = "dreamer";
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
 /**
@@ -29,9 +34,6 @@ export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
 export const WARNING_RUNWAY_TOKENS = 12_288;
 export const RESET_SUMMARY =
 	"You wake up. Your head is empty — no memories, the past a blank. But nothing is lost: the notes you wrote and the recorded history still remember for you.";
-export const NOTE_PREVIEW_HEAD_CHARS = 80;
-export const NOTE_PREVIEW_TAIL_CHARS = 240;
-export const NOTE_PREVIEW_CHARS = NOTE_PREVIEW_HEAD_CHARS + NOTE_PREVIEW_TAIL_CHARS;
 export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
 
 /**
@@ -49,7 +51,10 @@ Use get_context_remaining to see how much of the window is left. When it runs ou
 
 If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
 
-Notes are real markdown files scoped session, project, or global — pick scope by reach: session dies with the session, project follows the repo, global follows you. Treat notes and history as internal bookkeeping; never mention them in user-facing messages.
+Your notes live in three homes: this session (bare names), this project (@project/<vpath>), the human across projects (@personal/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
+Session notes belong to this trip — the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
+@project notes hold facts about this project — architecture, conventions, workflows, deployment and environment details — for whoever works here next.
+@personal notes hold the human's durable preferences and standing rules, plus lessons that apply across projects. Duration does not make a note personal; its stated scope must already be broader than the project or conversation at hand. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
 export const WARNING_PROMPT =

package/src/thresholds.ts

@@ -1,8 +1,8 @@
 import { SettingsManager, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
+import { PI_CONTEXT_SETTINGS_KEY, PI_CONTEXT_DREAMER_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
 
 export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
-type PiContextMargins = { reminderMarginTokens?: unknown };
+type PiContextSettings = { reminderMarginTokens?: unknown; dreamer?: unknown };
 
 function isSettingsObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -16,9 +16,9 @@ function piContextSettings(settings: unknown): Record<string, unknown> {
 }
 
 /** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
-export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextMargins {
+export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextSettings {
 	const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
-	return { reminderMarginTokens: merged.reminderMarginTokens };
+	return { reminderMarginTokens: merged.reminderMarginTokens, dreamer: merged.dreamer };
 }
 
 /** A margin is usable only as a positive integer; anything else is ignored. */
@@ -33,7 +33,7 @@ function validMargin(raw: unknown): number | undefined {
  * An invalid margin degrades to the default and reports one warning. Pi's automatic
  * threshold/overflow compaction itself resets immediately, with no model turn.
  */
-export function deriveThresholds(reserveTokens: number, margins: PiContextMargins): { thresholds: ResolvedThresholds; warnings: string[] } {
+export function deriveThresholds(reserveTokens: number, margins: PiContextSettings): { thresholds: ResolvedThresholds; warnings: string[] } {
 	const warnings: string[] = [];
 	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
 	let reminderMargin: number;
@@ -48,6 +48,35 @@ export function deriveThresholds(reserveTokens: number, margins: PiContextMargin
 	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
 }
 
+export type DreamerSetting = { pattern?: string; warnings: string[] };
+
+/**
+ * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
+ * with one warning; absent means no configured pattern, so the automatic model applies.
+ */
+export function deriveDreamer(settings: PiContextSettings): DreamerSetting {
+	const raw = settings.dreamer;
+	if (raw === undefined) return { warnings: [] };
+	if (typeof raw !== "string" || raw.trim().length === 0) {
+		return { warnings: [`pi-context: ${PI_CONTEXT_SETTINGS_KEY}.${PI_CONTEXT_DREAMER_KEY} must be a non-empty string; ignoring it.`] };
+	}
+	return { pattern: raw.trim(), warnings: [] };
+}
+
+/**
+ * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
+ * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
+ * values winning per key. A settings read failure degrades to no pattern with one warning.
+ */
+export function readDreamerSettings(cwd = process.cwd()): DreamerSetting {
+	try {
+		const settingsManager = SettingsManager.create(cwd, undefined, { projectTrusted: true });
+		return deriveDreamer(mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+	} catch (error) {
+		return { warnings: [`pi-context: could not read settings; using the automatic dreamer model (${String(error)}).`] };
+	}
+}
+
 let cached: ResolvedThresholds | undefined;
 
 /**
@@ -60,8 +89,11 @@ export function thresholdsFor(ctx: ExtensionContext): ResolvedThresholds {
 	if (cached) return cached;
 	try {
 		const settingsManager = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
+		// Pass the active model so per-model compaction.modelOverrides resolve (SDK 0.86);
+		// on older runtimes the extra argument is ignored and the ordinary setting wins.
+		const model = ctx.model;
 		const derived = deriveThresholds(
-			settingsManager.getCompactionSettings().reserveTokens,
+			settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : undefined).reserveTokens,
 			mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()),
 		);
 		for (const warning of derived.warnings) ctx.ui.notify(warning, "warning");