@astrosheep/pi-context 0.18.0 → 0.20.0

package/src/memory/store.ts

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, type Dirent } from "node:fs";
+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 { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
+import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { physicalPath, scopeDir, type Scope } from "./paths.js";
+
+export type { NoteMeta, Origin, Scope };
+
+export type NoteErrorCode = "not_found" | "ambiguous_edit" | "no_match" | "nothing_to_do" | "target_exists" | "too_large" | "invalid_scope" | "invalid_origin";
+
+/** Typed store refusal. `line_numbers` and `edit_index` are the edit error's addressing fields. */
+export class NoteError extends Error {
+	readonly code: NoteErrorCode;
+	readonly line_numbers?: number[];
+	readonly edit_index?: number;
+	constructor(code: NoteErrorCode, message: string, extra: { line_numbers?: number[]; edit_index?: number } = {}) {
+		super(message);
+		this.name = "NoteError";
+		this.code = code;
+		this.line_numbers = extra.line_numbers;
+		this.edit_index = extra.edit_index;
+	}
+}
+
+export type NoteRow = { path: string; meta: NoteMeta; sizeBytes: number };
+export type NoteMatch = { line: number; text: string; offsetChars: number };
+export type NoteSearchRow = { path: string; scope: Scope; meta: NoteMeta; matches: NoteMatch[] };
+
+const SCOPE_ORDER: readonly Scope[] = ["session", "project", "global"];
+
+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)})`);
+	return value;
+}
+
+function assertOrigin(value: unknown): Origin {
+	if (!isOrigin(value)) throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
+	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[];
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const paths: string[] = [];
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		const child = `${dir}/${entry.name}`;
+		if (entry.isDirectory()) paths.push(...walkMarkdown(child, base));
+		else if (entry.isFile() && entry.name.endsWith(".md")) paths.push(child.slice(base.length + 1).split("\\").join("/"));
+	}
+	return paths;
+}
+
+function matcherFor(pattern: unknown): RegExp | undefined {
+	const normalized = assertGlobPattern(pattern);
+	return normalized === undefined ? undefined : globToRegExp(normalized);
+}
+
+/**
+ * Every mutation lands through a tmp file renamed into place in the same directory, so a crash
+ * never leaves a torn note. No cross-process locking: out of scope by decision.
+ */
+function atomicWrite(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(tmp, content);
+		renameSync(tmp, path);
+	} catch (error) {
+		rmSync(tmp, { force: true });
+		throw error;
+	}
+}
+
+/** Write-time vpath guard: the byte cap is a tool-boundary rule, never a jail rule. */
+function assertWritablePath(vpath: string): void {
+	const bytes = Buffer.byteLength(vpath, "utf8");
+	if (bytes > MAX_NOTE_PATH_BYTES) throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
+}
+
+/** Serialized-size guard applied after the frontmatter is merged, before any bytes are written. */
+function assertSerializedSize(content: string): void {
+	const bytes = Buffer.byteLength(content, "utf8");
+	if (bytes > MAX_NOTE_BYTES) throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
+}
+
+/** Frontmatter block only (the body separator stripped), for the metadata-only diff. */
+function frontmatterOf(meta: NoteMeta): string {
+	return serializeNote(meta, "").slice(0, -2);
+}
+
+/** Line numbers (1-based) of every occurrence of `needle` in `body`. */
+function matchLineNumbers(body: string, needle: string): number[] {
+	const lines: number[] = [];
+	let cursor = 0;
+	for (;;) {
+		const index = body.indexOf(needle, cursor);
+		if (index === -1) break;
+		lines.push(body.slice(0, index).split("\n").length);
+		cursor = index + Math.max(needle.length, 1);
+	}
+	return lines;
+}
+
+export type WriteOptions = { scope: Scope; origin: Origin; stale?: boolean };
+
+/** Create or overwrite a note; overwrite keeps created_at and every unknown key. */
+export function writeNote(ctx: ExtensionContext, vpath: string, body: string, opts: WriteOptions): { meta: NoteMeta } {
+	assertVirtualPath(vpath);
+	assertWritablePath(vpath);
+	const scope = assertScope(opts.scope);
+	const origin = assertOrigin(opts.origin);
+	const path = physicalPath(scope, vpath, ctx);
+	const now = Date.now();
+	const cleanBody = stripLeadingFrontmatter(body);
+	const existing = existsSync(path) ? parseNote(readFileSync(path, "utf8"), now).meta : undefined;
+	const meta: NoteMeta = existing ?? {
+		scope,
+		origin,
+		status: "active",
+		stale: false,
+		created_at: now,
+		updated_at: now,
+		last_accessed: now,
+		access_count: 0,
+	};
+	meta.scope = scope;
+	meta.origin = origin;
+	meta.status = "active";
+	meta.stale = opts.stale ?? false;
+	meta.updated_at = now;
+	const serialized = serializeNote(meta, cleanBody);
+	assertSerializedSize(serialized);
+	atomicWrite(path, serialized);
+	return { meta };
+}
+
+export type EditOperation = { oldText: string; newText: string };
+export type EditOptions = { scope?: Scope; 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 } {
+	assertVirtualPath(vpath);
+	const path = physicalPath(scope, vpath, ctx);
+	if (!existsSync(path)) throw new NoteError("not_found", `note not found: ${vpath}`);
+	const parsed = parseNote(readFileSync(path, "utf8"));
+	const meta = { ...parsed.meta, scope };
+	mutate(meta);
+	meta.updated_at = Date.now();
+	const serialized = serializeNote(meta, parsed.body);
+	assertSerializedSize(serialized);
+	atomicWrite(path, serialized);
+	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 } {
+	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");
+	}
+	const found = resolve(ctx, vpath);
+	if (!found) throw new NoteError("not_found", "note not found");
+	const { meta, body } = parseNote(found.raw);
+	// 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,
+	// so a failing edit leaves the file byte-identical (frontmatter included).
+	let next = body;
+	operations.forEach((edit, index) => {
+		const oldText = edit?.oldText;
+		const newText = edit?.newText;
+		if (typeof oldText !== "string" || oldText.length === 0) throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { edit_index: index });
+		if (typeof newText !== "string") throw new NoteError("no_match", `edit ${index}: newText must be a string`, { edit_index: index });
+		const lines = matchLineNumbers(next, oldText);
+		if (lines.length === 0) throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { edit_index: index });
+		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);
+	});
+	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.
+	const bodyChanged = body !== next;
+	const metadataChanged = beforeMeta.scope !== meta.scope || beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+	const diff = bodyChanged && metadataChanged
+		? generateDiffString(found.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 };
+}
+
+/** 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 {
+	assertVirtualPath(vpath);
+	const found = resolve(ctx, vpath, opts.scope);
+	if (!found) return undefined;
+	const now = Date.now();
+	const { meta, body } = parseNote(found.raw, now);
+	meta.scope = found.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 };
+}
+
+/** Merged rows across scopes, most recently updated first (path then scope break 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)) {
+		const root = scopeDir(scope, ctx);
+		for (const path of walkMarkdown(root)) {
+			if (matcher && !matcher.test(path)) continue;
+			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+			meta.scope = scope;
+			rows.push({ path, meta, 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));
+	return rows;
+}
+
+/** Case-sensitive literal substring search over note bodies, with a match address per line. */
+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)) {
+		const root = scopeDir(scope, ctx);
+		for (const path of walkMarkdown(root)) {
+			if (matcher && !matcher.test(path)) 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) });
+				}
+				baseChars += Array.from(line).length + 1;
+			}
+			if (matches.length > 0) rows.push({ path, scope, meta, matches });
+		}
+	}
+	rows.sort((a, b) => a.path.localeCompare(b.path) || a.scope.localeCompare(b.scope));
+	return rows;
+}

package/src/memory/tools.ts

@@ -0,0 +1,175 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { localIso } from "../notes.js";
+import { characterWindowHeader, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
+import { serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+import type { Scope } from "./paths.js";
+
+const SCOPE = Type.Optional(
+	Type.Union([Type.Literal("session"), Type.Literal("project"), Type.Literal("global")], {
+		description:
+			"The note's reach — which root it lives under. session: only this session needs it (checkpoints, scratch state, worker rosters); dies with the session. project: tied to the current working directory — design decisions and repo facts that future sessions here still need. global: follows you everywhere — user laws, preferences, cross-project maps. On write, picks the destination root (default: session). Omit on read/list/search to cover all three; a read resolves session → project → global and returns the first existing file.",
+	}),
+);
+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.",
+	}),
+);
+
+/** Render epoch-ms metadata as the same local ISO timestamps the frontmatter carries. */
+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) };
+}
+
+/** Turn a typed store refusal into the pinned error arm; unknown errors stay thrown. */
+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 registerMemoryTools(pi: ExtensionAPI) {
+	pi.registerTool(defineTool({
+		name: "notes_write",
+		label: "Notes write",
+		description: "Create or replace a note as a real markdown file under the session, project, or global note root. 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({ path: Type.String(), content: Type.String(), scope: SCOPE, origin: ORIGIN, stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+		// A batch containing write or edit runs one call at a time, so note read-modify-write cannot race.
+		executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			const content = params.content;
+			try {
+				const { meta } = writeNote(ctx, params.path, content, { scope: (params.scope ?? "session") as Scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				return output({ path: params.path, 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. 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 scope/origin/stale. scope/origin/stale are setters: scope moves the file, refusing when the target already exists. The success return carries resolved_scope and a diff of what changed.",
+		parameters: Type.Object({ path: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), scope: SCOPE, 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 { meta, applied, resolved_scope, diff } = editNote(ctx, params.path, params.edits, { scope: params.scope as Scope | undefined, origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				return output({ path: params.path, 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: 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 12000, max 50000). 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 file, the resolved offset, the delivered char range, and the resume cursor.",
+		parameters: Type.Object({ path: Type.String(), scope: SCOPE, 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: 50000, description: "Largest requested window in code points (default 12000). 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 {
+				note = readNote(ctx, params.path, { scope: params.scope as Scope | undefined });
+			} catch (error) {
+				return failure(error);
+			}
+			if (!note) return output({ error: "note not found", path: params.path });
+			const text = serializeNote(note.meta, note.body);
+			const totalChars = Array.from(text).length;
+			// A positive offset past the end is an addressing error, not an empty page.
+			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)`, path: params.path, 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 ?? 12000, 50000);
+			return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...rest } = window;
+				return outputRaw(characterWindowHeader(params.path, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { path: params.path, 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 path, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. Without scope, all three scopes are merged; a glob pattern (* within a path segment, ** across segments) filters the virtual paths.",
+		parameters: Type.Object({ scope: SCOPE, 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, { scope: params.scope as Scope | undefined, pattern: params.pattern ?? undefined });
+			} catch (error) {
+				return failure(error);
+			}
+			const files: Array<{ path: string; scope: Scope; origin: Origin; status: string; stale: boolean; size_bytes: number; created_at: string; updated_at: string; path_truncated?: boolean }> = rows.map((row) => ({
+				path: row.path,
+				scope: row.meta.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 path = middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate, path_truncated: true }));
+				return { ...file, path, path_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. Without scope, all three scopes are merged and every entry carries its scope. 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(), scope: SCOPE, 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, { scope: params.scope as Scope | undefined, pattern: params.pattern ?? undefined });
+			} catch (error) {
+				return failure(error);
+			}
+			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+			const result: Array<{ path: string; scope: Scope; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; path_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 { path: row.path, 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) };
+			});
+			// Trailing matches are dropped to fit the budget, named by matches_total; a single
+			// over-budget line is delivered as a flagged prefix; only a pathological path is
+			// middle-truncated, and then only with a visible path_truncated flag.
+			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: (typeof result)[number] = fitted(text);
+				if (fits(prefix)) return prefix;
+				const path = middleTruncate(prefix.path, (candidate) => fits({ ...prefix, path: candidate, path_truncated: true }));
+				return { ...prefix, path, path_truncated: true };
+			};
+			return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+		},
+	}));
+}

package/src/prompts.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { historyFromSession } from "./history.js";
-import { notesFromSession, localIso } from "./notes.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";
 
 /** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
@@ -23,23 +24,33 @@ function identityBlock(agentName: string, firstWindowId: string, currentWindowId
  * as tail content. Stale notes are excluded entirely; empty when no fresh notes remain.
  */
 function notesIndex(ctx: ExtensionContext): string {
-	const recentNotes = [...notesFromSession(ctx)]
-		.filter(([, file]) => !file.stale)
-		.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
-		.slice(0, 3);
-	if (recentNotes.length === 0) return "";
-	const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (up to 3, most recent first):`];
-	for (const [path, file] of recentNotes) {
-		lines.push(`- ${path} (${file.text.split("\n").length} lines, ${Buffer.byteLength(file.text, "utf8")} UTF-8 bytes, updated ${localIso(file.updatedAt)})`);
-		const chars = Array.from(file.text);
-		// 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
-			? file.text
-			: `${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"));
+	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);
 	}
-	return lines.join("\n");
+	// 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);
+	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):`];
+		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"));
+		}
+		sections.push(lines.join("\n"));
+	}
+	return sections.join("\n\n");
 }
 
 /**

package/src/protocol.ts

@@ -26,7 +26,7 @@ export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
  * line (reserve + WARNING_RUNWAY_TOKENS); what lies below is overdraft the model
  * never sees — Codex's fallback buffer, relocated above the line.
  */
-export const WARNING_RUNWAY_TOKENS = 8_192;
+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;
@@ -40,17 +40,17 @@ export const CONTINUATION = "Your memory was just erased. Pull only the details
  * it is never re-injected, so it stays cache-stable at the head of the window.
  */
 export const PROTOCOL_BLOCK = `${CONTEXT_WINDOW_PROTOCOL_OPEN_TAG}
-Your memory resets whenever the context window fills; only what you wrote down survives. Two things remember for you, and both outlive every window in this session: your notes, and this session's recorded history. Write notes with notes_write_file / notes_append_to_file, read them back with notes_read_file / notes_search_contents; history is read-only through the history_* tools. Everything else wakes blank.
+Your memory resets whenever the context window fills; only what you wrote down survives. Two things remember for you, and both outlive every window in this session: your notes, and this session's recorded history. Write notes with notes_write, revise them with notes_edit, and read them back with notes_read / notes_search / notes_list; history is read-only through the history_* tools. Everything else wakes blank.
+Mark outdated or unneeded notes stale — leave them, and they will keep misleading you.
 
-Keep a running checkpoint while you work, not at the last minute — the next window wakes knowing nothing about the work: 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. history_list_items returns those IDs; history_read_item pulls the exact item back out. Bookmark anything expensive the same way — a window/item ID beats re-running or re-searching.
+Keep a running checkpoint while you work, not at the last minute — the next window wakes knowing nothing about the work: 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. history_list returns those IDs; history_read pulls the exact item back out. Bookmark anything expensive the same way — a window/item ID beats re-running or re-searching.
 
 Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone — with no final turn at the limit — and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can end the window yourself with new_context instead of waiting for the erase. Do not let a window die undocumented.
 
-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_item directly when you know the window and item IDs, history_list_items or history_search_contents to find them when you don't.
+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 session-scoped virtual files. Treat notes and history as internal bookkeeping; never mention them in user-facing messages.
+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.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
 export const WARNING_PROMPT =
-	"Your memory is about to be erased. Write the note. NOW. If it already exists, append instead: 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. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";
-
+	"Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): 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. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";