@astrosheep/pi-context 0.18.0 → 0.19.0

package/README.md

@@ -20,19 +20,19 @@ pi -e npm:@astrosheep/pi-context
 - **A boot block at every window head** — static once-per-window content (cache-stable) carrying the window identity, the recent-notes index, and a short protocol that teaches the model how to recover: notes for its own bookkeeping, history tools for everything before the reset.
 - **Low-budget guidance** — one persisted early warning per window when the estimated remaining budget crosses the reminder line, so the model checkpoints before the lights go out.
 - **`get_context_remaining`** — the live, reserve-adjusted estimate of the context budget left before Pi's compaction reserve.
-- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace:
+- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace; notes are real markdown files under `~/.agents/notes` (`global/`, `project/`, `pi/session/`):
 
 | Codex action | Pi tool |
 | --- | --- |
-| `history.list_windows` | `history_list_windows` |
-| `history.list_items` | `history_list_items` |
-| `history.read_item` | `history_read_item` |
-| `history.search_contents` | `history_search_contents` |
-| `notes.list_files` | `notes_list_files` |
-| `notes.read_file` | `notes_read_file` |
-| `notes.search_contents` | `notes_search_contents` |
-| `notes.append_to_file` | `notes_append_to_file` |
-| `notes.write_file` | `notes_write_file` |
+| `history.list_windows` | `history_windows` |
+| `history.list_items` | `history_list` |
+| `history.read_item` | `history_read` |
+| `history.search_contents` | `history_search` |
+| `notes.write` | `notes_write` |
+| `notes.edit` | `notes_edit` |
+| `notes.read` | `notes_read` |
+| `notes.list` | `notes_list` |
+| `notes.search` | `notes_search` |
 
 The tool descriptions the model sees are the behavioral documentation: search is case-sensitive literal substring; reads are character windows whose cursors reconstruct the original exactly; anything a response does not deliver is named by an explicit field.
 

package/docs/reset-lifecycle.md

@@ -13,7 +13,7 @@
 | Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
 | Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
 
-The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+8192 tokens remaining. After it, the model either ends the window itself with `new_context` or rides into Pi's automatic compaction, which resets on the spot with no turn.
+The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+12288 tokens remaining. After it, the model either ends the window itself with `new_context` or rides into Pi's automatic compaction, which resets on the spot with no turn.
 
 The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. An explicit reset uses the manual `ctx.compact` route and therefore needs this completion logic; an automatic compaction is already the reset and resumes through Pi's own caller.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/history-tools.ts

@@ -31,7 +31,7 @@ function truncateHistoryItem<T extends { truncated_content: string; truncated: b
 
 export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
-		name: "history_list_windows",
+		name: "history_windows",
 		label: "History list windows",
 		description: "List durable Pi session-history windows.",
 		parameters: Type.Object({ limit: positiveInteger(), recent_first: recentFirst() }, { additionalProperties: false }),
@@ -44,9 +44,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_list_items",
+		name: "history_list",
 		label: "History list items",
-		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read_item.",
+		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);
@@ -59,7 +59,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_read_item",
+		name: "history_read",
 		label: "History read item",
 		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
 		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. 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." })), window_id: Type.String() }, { additionalProperties: false }),
@@ -81,9 +81,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_search_contents",
+		name: "history_search",
 		label: "History search",
-		description: "Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Invocations and outputs are separate items (roles \"tool_call\" and \"tool\"), so both are searchable; the role parameter's description enumerates all six. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read_item at match_offset_chars.",
+		description: "Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Invocations and outputs are separate items (roles \"tool_call\" and \"tool\"), so both are searchable; the role parameter's description enumerates all six. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read at match_offset_chars.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);

package/src/history.ts

@@ -72,7 +72,7 @@ function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "output
  * An assistant turn's tool calls, projected as their own items: calls wear their own role so the
  * authoring turn's visible text (role "assistant") stays pure; what was invoked stays as
  * searchable as what came back (role "tool"). Ids derive from the turn's entry id and stay
- * opaque; history_read_item resolves them like any other item.
+ * opaque; history_read resolves them like any other item.
  */
 function toolCallItems(windowId: string, entry: { id: string; timestamp?: string }, message: AgentMessage): HistoryItem[] {
 	if (message.role !== "assistant" || !Array.isArray(message.content)) return [];

package/src/index.ts

@@ -1,5 +1,5 @@
 import { registerHistoryTools } from "./history-tools.js";
-import { registerNoteTools } from "./note-tools.js";
+import { registerMemoryTools } from "./memory/tools.js";
 import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
 import { output } from "./tool-output.js";
 export { deriveThresholds, mergePiContextSettings };
@@ -48,7 +48,7 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	registerHistoryTools(pi);
-	registerNoteTools(pi);
+	registerMemoryTools(pi);
 
 	pi.registerTool(defineTool({
 		name: "new_context",

package/src/memory/frontmatter.ts

@@ -0,0 +1,153 @@
+import { localIso } from "../notes.js";
+import type { Scope } from "./paths.js";
+
+export type NoteStatus = "active" | "superseded" | "pending" | "archived";
+export type Origin = "user" | "self" | "external";
+
+/**
+ * Harness-owned note metadata. The eight required keys are always written; the four optional
+ * sleep-shift keys survive this layer untouched when present. `[key: string]: unknown` carries
+ * any frontmatter key this layer does not know, preserved verbatim across rewrites.
+ */
+export type NoteMeta = {
+	scope: Scope;
+	origin: Origin;
+	status: NoteStatus;
+	stale: boolean;
+	created_at: number;
+	updated_at: number;
+	last_accessed: number;
+	access_count: number;
+	source_window?: string;
+	supersedes?: string;
+	recurrence_count?: number;
+	recurrence_windows?: string[];
+	[key: string]: unknown;
+};
+
+const SCOPES: readonly Scope[] = ["session", "project", "global"];
+const ORIGINS: readonly Origin[] = ["user", "self", "external"];
+const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
+const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"] as const;
+/** Emission order, exactly the Design's key list. */
+const KNOWN_KEYS = ["scope", "origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
+
+export function isScope(value: unknown): value is Scope {
+	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
+}
+
+export function isOrigin(value: unknown): value is Origin {
+	return typeof value === "string" && (ORIGINS as readonly string[]).includes(value);
+}
+
+function isStatus(value: unknown): value is NoteStatus {
+	return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
+}
+
+function toEpoch(value: unknown, fallback: number): number {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Date.parse(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+
+/** A frontmatter scalar encoded as JSON, falling back to a plain string for hand-written YAML. */
+function parseScalar(text: string): unknown {
+	const trimmed = text.trim();
+	if (trimmed === "") return "";
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) return trimmed.slice(1, -1);
+		return trimmed;
+	}
+}
+
+/**
+ * Split raw file text into its frontmatter fields and body. When the file does not open with
+ * a closed `---` block, the whole text is body and the field map is empty.
+ */
+function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body: string } {
+	const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+	const lines = stripped.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+	if (lines[0]?.trim() !== "---") return { fields: {}, body: raw };
+	let close = -1;
+	for (let index = 1; index < lines.length; index++) {
+		if (lines[index]?.trim() === "---") {
+			close = index;
+			break;
+		}
+	}
+	if (close === -1) return { fields: {}, body: raw };
+	const fields: Record<string, unknown> = {};
+	for (let index = 1; index < close; index++) {
+		const line = lines[index]!;
+		const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
+		if (!match) continue;
+		const key = match[1]!;
+		const rest = match[2]!;
+		if (rest.trim() === "") {
+			// A bare key opens a block sequence of `- item` lines, the only multi-line shape we parse.
+			const items: unknown[] = [];
+			while (index + 1 < close && /^\s*-\s+/.test(lines[index + 1]!)) {
+				index++;
+				items.push(parseScalar(lines[index]!.replace(/^\s*-\s+/, "")));
+			}
+			fields[key] = items;
+		} else {
+			fields[key] = parseScalar(rest);
+		}
+	}
+	const rest = lines.slice(close + 1);
+	if (rest[0] === "") rest.shift();
+	return { fields, body: rest.join("\n") };
+}
+
+/**
+ * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
+ * access_count 0, timestamps now); unknown keys are carried through untouched.
+ */
+export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
+	const { fields, body } = parseFrontmatter(raw);
+	const meta = { ...fields } as Record<string, unknown>;
+	meta.scope = isScope(meta.scope) ? meta.scope : "global";
+	meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
+	meta.status = isStatus(meta.status) ? meta.status : "active";
+	meta.stale = meta.stale === true;
+	for (const key of TIMESTAMP_KEYS) meta[key] = toEpoch(meta[key], now);
+	meta.access_count = typeof meta.access_count === "number" && Number.isFinite(meta.access_count) ? meta.access_count : 0;
+	return { meta: meta as NoteMeta, body };
+}
+
+/** Emit a YAML scalar: bare for safe strings and JSON literals, JSON-quoted otherwise. */
+function yamlScalar(value: unknown): string {
+	if (typeof value === "string") {
+		const reserved = new Set(["true", "false", "null", "yes", "no", "on", "off", "~"]);
+		if (/^[A-Za-z0-9_.+\-:/]+$/.test(value) && !reserved.has(value.toLowerCase())) return value;
+	}
+	return JSON.stringify(value);
+}
+
+/** Serialize frontmatter + blank line + body. Known keys emit in Design order, extras after. */
+export function serializeNote(meta: NoteMeta, body: string): string {
+	const lines: string[] = [];
+	for (const key of KNOWN_KEYS) {
+		const value = meta[key];
+		if (value === undefined) continue;
+		if ((TIMESTAMP_KEYS as readonly string[]).includes(key)) lines.push(`${key}: ${yamlScalar(localIso(value as number))}`);
+		else lines.push(`${key}: ${yamlScalar(value)}`);
+	}
+	for (const key of Object.keys(meta)) {
+		if ((KNOWN_KEYS as readonly string[]).includes(key)) continue;
+		if (meta[key] === undefined) continue;
+		lines.push(`${key}: ${yamlScalar(meta[key])}`);
+	}
+	return `---\n${lines.join("\n")}\n---\n\n${body}`;
+}
+
+/** Strip a leading frontmatter block from user content, so a note body is pure content. */
+export function stripLeadingFrontmatter(content: string): string {
+	return parseFrontmatter(content).body;
+}

package/src/memory/paths.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+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";
+
+/** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
+export function notesRoot(): string {
+	const override = process.env.PI_NOTES_HOME;
+	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+
+/**
+ * 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.
+ */
+function gitRoot(cwd: string): string | undefined {
+	let dir = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
+export function projectKey(cwd: string): string {
+	const absolute = resolve(cwd);
+	const root = gitRoot(absolute) ?? absolute;
+	const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
+	return `${basename(root)}-${digest}`;
+}
+
+/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
+function sessionId(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionId();
+}
+
+/** 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 === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
+	return join(notesRoot(), "pi", "session", sessionId(ctx));
+}
+
+/**
+ * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
+ * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
+ */
+export function noteFileName(vpath: string): string {
+	return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
+}
+
+/** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
+export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext): string {
+	return join(scopeDir(scope, ctx), ...noteFileName(vpath).split("/"));
+}

package/src/memory/store.ts

@@ -0,0 +1,295 @@
+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 };
+
+/** 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,166 @@
+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")]));
+const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")]));
+
+/** 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; 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. 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.";
-

package/src/note-tools.ts

@@ -1,171 +0,0 @@
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
-import { nullableString, positiveInteger, cursor, searchQuery, searchQueries } from "./tool-schema.js";
-import { notesFromSession, assertVirtualPath, assertGlobPattern, globToRegExp, localIso, type NoteOperation } from "./notes.js";
-import { NOTE_TYPE, MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./protocol.js";
-
-export function registerNoteTools(pi: ExtensionAPI) {
-	const saveNote = (op: NoteOperation) => {
-		// pi.appendEntry writes a custom SessionManager entry. Custom entries are persistent but excluded from LLM context.
-		// ExtensionContext deliberately exposes only a readonly SessionManager, so this is the public extension write path.
-		pi.appendEntry(NOTE_TYPE, op);
-	};
-
-	pi.registerTool(defineTool({
-		name: "notes_list_files",
-		label: "Notes list files",
-		description: "List note files, optionally filtered by a glob pattern (* within a path segment, ** across segments). The default order is most recently updated first; file_order_by (name, created_at, updated_at) and file_order (ascending, descending) select another. Entries carry each file's stale flag.",
-		parameters: Type.Object({ pattern: nullableString(), max_results: positiveInteger(), cursor: cursor(), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
-		async execute(_id, params, _signal, _update, ctx) {
-			const pattern = assertGlobPattern(params.pattern);
-			const matcher = pattern ? globToRegExp(pattern) : undefined;
-			let files = [...notesFromSession(ctx)].filter(([path]) => !matcher || matcher.test(path));
-			const key = params.file_order_by ?? "updated_at";
-			// Deterministic total order: (axis key, createdAt, path) ascending. Paths are unique, so
-			// this never depends on map iteration order; descending reverses the whole comparator.
-			files.sort(([aPath, a], [bPath, b]) => {
-				const primary = key === "name" ? aPath.localeCompare(bPath) : key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt;
-				if (primary !== 0) return primary;
-				if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
-				return aPath.localeCompare(bPath);
-			});
-			// An explicit file_order always wins; otherwise the axis's natural direction applies
-			// (descending for the time axes, ascending for name).
-			if (params.file_order ? params.file_order === "descending" : key !== "name") files.reverse();
-			const listed: Array<{ path: string; size_bytes: number; stale: boolean; created_at: string; updated_at: string; path_truncated?: boolean }> = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
-			// `path` is the entry's identity: return it intact whenever the entry fits, and only
-			// ever alter it together with a visible `path_truncated: true` flag. A pathological
-			// legacy path predating the write cap is the one case that cannot fit at all.
-			return output(page(listed, 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_read_file",
-		label: "Notes read file",
-		description: "Read a character window from a note file: offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end (offset_chars: -2000 reads the last 2000) — 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 note text behind a one-line [bracketed] header naming the file, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
-		parameters: Type.Object({ path: 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: 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) {
-			const path = assertVirtualPath(params.path);
-			const file = notesFromSession(ctx).get(path);
-			if (!file) return output({ error: "note file not found", path });
-			const totalChars = Array.from(file.text).length;
-			// A positive offset past the end is an addressing error, not an empty page: say so,
-			// and name the largest legal offset (offset == total stays the legal empty end-read).
-			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, offset_chars: params.offset_chars, total_chars: totalChars });
-			}
-			const created_at = localIso(file.createdAt);
-			const updated_at = localIso(file.updatedAt);
-			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
-			return readCharacterWindow(file.text, params.offset_chars, params.limit_chars, (window) => {
-				const { content, ...cursor } = window;
-				return outputRaw(characterWindowHeader(path, window, ` · created ${created_at} · updated ${updated_at}`), content, { path, ...cursor, limit_chars, created_at, updated_at });
-			}, (result) => withinTextBudget(result.content[0].text));
-		},
-	}));
-
-	pi.registerTool(defineTool({
-		name: "notes_search_contents",
-		label: "Notes search",
-		description: "Case-sensitive literal substring search over note lines; query is one string or several (OR), each matched line appears once. No semantic search. Optionally filtered by a glob pattern (* within a path segment, ** across segments). Each file entry carries matches_total, its full match count before capping: matches_total minus matches.length is how many were dropped. Each match carries line and offset_chars (the file-absolute code-point offset of the earliest match): notes_read_file at offset_chars shows the query. An over-budget matched line comes back as a prefix with truncated and total_chars; read the rest at the same offset_chars.",
-		parameters: Type.Object({ max_matches_per_file: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), pattern: nullableString() }, { additionalProperties: false }),
-		async execute(_id, params, _signal, _update, ctx) {
-			const queries = searchQueries(params.query);
-			const pattern = assertGlobPattern(params.pattern);
-			const matcher = pattern ? globToRegExp(pattern) : undefined;
-			let files = [...notesFromSession(ctx)].filter(([path]) => !matcher || matcher.test(path));
-			if (params.recent_file_first) files.sort((a, b) => b[1].createdAt - a[1].createdAt);
-			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
-			const result: Array<{ path: string; 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 }> = files
-				.map(([path, file]) => {
-					// A match's offset_chars is file-absolute: the code points before its line, plus the
-					// earliest occurrence of any query inside that line. Search then composes with
-					// notes_read_file exactly like history_search_contents composes with history_read_item.
-					let baseChars = 0;
-					const allMatches = file.text.split("\n").flatMap((line, index) => {
-						const match = queries.some((query) => line.includes(query))
-							? [{ line: index + 1, text: line, truncated: false, total_chars: Array.from(line).length, offset_chars: baseChars + earliestMatchOffsetChars(line, queries) }]
-							: [];
-						baseChars += Array.from(line).length + 1;
-						return match;
-					});
-					return { path, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt), matches_total: allMatches.length, matches: allMatches.slice(0, maxPerFile) };
-				})
-				.filter((file) => file.matches.length > 0);
-			// Trailing matches are dropped to fit the budget (bounded by a monotone binary search),
-			// and the entry's matches_total keeps naming the drop. Only when a single intact match is
-			// over budget is its line delivered as a plain prefix, flagged and counted. Only when the
-			// entry cannot fit even then is the identity field itself truncated, and then only together
-			// with a visible `path_truncated: true` flag.
-			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
-				if (fits(file)) return file;
-				const matches = file.matches;
-				// First, drop whole trailing matches: the largest prefix that fits intact is kept, so an
-				// entry only truncates a line when that single line alone is over budget.
-				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) };
-				// Even one intact match is over budget: keep the first match as a plain, named prefix.
-				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));
-		},
-	}));
-
-	for (const [name, op] of [["notes_append_to_file", "append"], ["notes_write_file", "write"]] as const) {
-		pi.registerTool(defineTool({
-			name,
-			label: name === "notes_append_to_file" ? "Notes append" : "Notes write",
-			description: name === "notes_append_to_file"
-				? "Append exact text to a note file. Appending suits chronological logs; for current-state notes use notes_write_file instead. mark_stale closes a note."
-				: "Create or replace a note file. Keep notes small and split by topic; replace outdated notes whole. mark_stale: true flags a note stale (optionally with its final content): stale notes leave the boot index but stay readable and searchable; rewriting revives them.",
-			parameters: Type.Object({ text: Type.Optional(Type.String()), path: Type.String(), mark_stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
-			// Codex sets supports_parallel_tool_calls = false on notes.write_file/append_to_file.
-			// Pi's per-tool equivalent is executionMode "sequential": a batch containing either
-			// tool runs its calls one at a time, so note read-modify-write cannot race.
-			executionMode: "sequential",
-			async execute(_id, params, _signal, _update, ctx) {
-				const path = assertVirtualPath(params.path);
-				const pathBytes = Buffer.byteLength(path, "utf8");
-				// The cap lives here, at the tool boundary, and never in assertVirtualPath: note
-				// replay validates persisted ops through that helper and must keep loading sessions
-				// that already contain a longer legacy path (reads stay un-capped too).
-				if (pathBytes > MAX_NOTE_PATH_BYTES) return output({ error: `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes`, path_bytes: pathBytes });
-				const hasText = params.text !== undefined;
-				const hasStale = params.mark_stale !== undefined;
-				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });
-				const old = notesFromSession(ctx).get(path);
-				if (!hasText && !old) return output({ error: "note file not found", path });
-				// Appending is not creating: an append to a path that does not exist almost always
-				// means a typo'd path, so it dies loudly instead of silently minting a new note.
-				if (op === "append" && hasText && !old) return output({ error: "note file not found (use notes_write_file to create)", path });
-				const next = hasText ? (op === "append" ? `${old?.text ?? ""}${params.text}` : params.text as string) : old!.text;
-				const bytes = Buffer.byteLength(next, "utf8");
-				if (hasText && bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });
-				const now = Date.now();
-				const operation: NoteOperation = { op, path, createdAt: old?.createdAt ?? now, updatedAt: now };
-				if (hasText) operation.text = params.text;
-				if (hasStale) operation.stale = params.mark_stale;
-				saveNote(operation);
-				return output({ path, size_bytes: bytes, operation: op, stale: hasStale ? params.mark_stale : false });
-			},
-		}));
-	}
-}