@skydiveai/pi-extensions 0.1.0-beta.1565 → 0.1.0-beta.1569

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { DefaultExecutionEventBusManager, DefaultRequestHandler, InMemoryTaskStore } from "@a2a-js/sdk/server";
 import { UserBuilder, restHandler } from "@a2a-js/sdk/server/express";
 import { buildAgentCard, chainMiddleware, composeHandlers, createAgentExecutor, createProtocolHandlers, getCurrentTraceparent, logger, mountAt, requestHeaders, requestUrl, webHandlerToMiddleware } from "@skydiveai/pi-server";
-import { mkdir, open, readFile, readdir, stat, unlink } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { z } from "zod";
 import { pathToFileURL } from "node:url";
@@ -2737,37 +2737,35 @@ const currentTimeExtension = (pi) => {
 //#endregion
 //#region src/memory.ts
 /**
-* In-harness memory index builder.
+* In-harness memory readers.
 *
-* The agent has an agent-level file-based memory at `<cwd>/.memory/`,
-* organized by directory:
+* The agent has an agent-level file-based memory at `<cwd>/.memory/`, split
+* into two halves that are surfaced differently:
 *
-*   .memory/users/<id>-<name>/<topic>.md
-*   .memory/projects/<project_slug>/<topic>.md
-*   .memory/feedback/<topic>.md
-*   .memory/reference/<topic>.md
+* 1. Shared knowledge (projects, lessons, external systems) — indexed by a
+*    single hand-maintained `<cwd>/.memory/MEMORY.md` that the *agent* writes
+*    and curates, Claude-Code style: one line per fact pointing at the file
+*    that holds it. `readMemoryIndexFile` just reads that file; the agent owns
+*    its contents. This is the whole index for the shared half — there is no
+*    derived walk and no per-directory `MEMORY.md`.
 *
-* The path encodes type and subject (for `users/`, the subject is the
-* person's stable id with a readable name suffix); each `.md` file's
-* frontmatter only carries `name` and `description`.
+* 2. Per-person memory — `.memory/users/<id>-<name>/<topic>.md`. This half is
+*    *derived*, not hand-maintained, because it has to be filtered to the one
+*    person on the current turn (a single hand-written index couldn't be
+*    scoped per-user without leaking one person's notes into another's
+*    conversation). `buildMemoryIndex` walks a single user's directory, reads
+*    only the frontmatter of each `.md` (open fd → read first ~4KB → close, in
+*    parallel), and renders an index. Each `.md`'s frontmatter carries `name`
+*    and `description`; bodies are never read — the agent loads a specific
+*    memory's body on demand via the `read` tool.
 *
-* `buildMemoryIndex` walks `.memory/` by type directory, reads only the
-* frontmatter of each `.md` (open fd → read first ~4KB → close, in
-* parallel), and renders a markdown index grouped by type and (where
-* applicable) by subject. Files outside the four type directories are
-* ignored. Bodies are never read — the agent loads a specific memory's
-* body on demand via the `read` tool when the index entry says it's
-* relevant.
+* Mtime cache (for the derived per-user half) keyed by cwd — within the
+* lifetime of a sandbox the cwd is fixed, so this is effectively a single-entry
+* cache. It invalidates when any `.md` under `users/` is added/modified/
+* deleted; turns where memory didn't change reuse the cached entries.
 *
-* Mtime cache keyed by cwd — within the lifetime of a sandbox the cwd
-* is fixed, so this is effectively a single-entry cache. Cache invalidates
-* when any `.md` in the tree is added/modified/deleted; turns where
-* memory didn't change reuse the cached string.
-*
-* Frontmatter is parsed as YAML (`yaml` package) and validated with a
-* zod schema — files that don't match the shape are dropped from the
-* index. The same schema can be reused at write time if we want to
-* validate before commit.
+* Frontmatter is parsed as YAML (`yaml` package) and validated with a zod
+* schema — files that don't match the shape are dropped from the index.
 */
 const FRONTMATTER_READ_BYTES = 4096;
 const FrontmatterSchema = z.object({
@@ -2775,33 +2773,118 @@ const FrontmatterSchema = z.object({
 	description: z.string().min(1)
 }).passthrough();
 const MEMORY_DIRNAME = ".memory";
-const TYPE_DIRS = [
-	"users",
-	"projects",
-	"feedback",
-	"reference"
+const MEMORY_INDEX_FILENAME = "MEMORY.md";
+const USERS_DIRNAME = "users";
+/**
+* The shared-knowledge type dirs from the old frontmatter-indexed layout, used
+* only to seed a `MEMORY.md` for agents created before it existed (see
+* `seedMemoryIndexFile`). `users/` is deliberately excluded — per-person memory
+* stays derived and never lands in the shared, un-scoped `MEMORY.md`.
+*/
+const LEGACY_SHARED_TYPES = [
+	{
+		dir: "projects",
+		label: "Projects"
+	},
+	{
+		dir: "feedback",
+		label: "Feedback"
+	},
+	{
+		dir: "reference",
+		label: "Reference"
+	}
 ];
-const TYPES_WITH_SUBJECT = new Set(["users", "projects"]);
-const TYPE_LABELS = {
-	users: "Users",
-	projects: "Projects",
-	feedback: "Feedback",
-	reference: "Reference"
-};
+/**
+* Soft budget for an injected index block. The index is read and injected into
+* the system prompt on every turn, so every entry costs context for the rest of
+* the conversation. Past this size we nudge the agent to consolidate and prune
+* rather than keep appending. Not a hard cap — nothing is truncated.
+*/
+const MEMORY_INDEX_SOFT_BUDGET_CHARS = 2e4;
+/**
+* Hard cap on the injected index — double the soft budget. The soft budget only
+* warns; this actually bounds what we inject so a runaway index can't consume
+* unbounded context on every turn. Past this, the index is truncated (on a line
+* boundary) before injection. It's a backstop, not a normal operating point.
+*/
+const MEMORY_INDEX_HARD_BUDGET_CHARS = MEMORY_INDEX_SOFT_BUDGET_CHARS * 2;
+/**
+* Cheap size summary of a rendered index block, used to surface how much of the
+* every-turn context budget the index is spending so the agent keeps it lean.
+* Counts pointer/file lines — both the derived `` - `path` — desc`` form and
+* the hand-maintained `- [Title](path) — hook` form — not the group headers.
+*/
+function summarizeIndex(index) {
+	const entryCount = index.split("\n").filter((line) => /^\s*- (?:`|\[)/.test(line)).length;
+	const charCount = index.length;
+	return {
+		entryCount,
+		charCount,
+		overBudget: charCount > MEMORY_INDEX_SOFT_BUDGET_CHARS
+	};
+}
+/**
+* One-line size note for an index block header, e.g. `12 entries, 3187 chars`.
+*/
+function indexSizeNote(index) {
+	const { entryCount, charCount } = summarizeIndex(index);
+	return `${entryCount} ${entryCount === 1 ? "entry" : "entries"}, ${charCount} chars`;
+}
+/**
+* An explicit warning to surface to the agent when an index has grown past its
+* budget, or `null` when it's within budget. Extensions render this prominently
+* above the index so the agent prunes before it keeps appending.
+*/
+function indexBudgetWarning(index) {
+	const { charCount, overBudget } = summarizeIndex(index);
+	if (!overBudget) return null;
+	return `⚠️ This memory index is ${charCount} chars, over its ${MEMORY_INDEX_SOFT_BUDGET_CHARS}-char budget. It's costing you context on every turn — consolidate duplicate entries and delete stale ones to bring it back under budget before adding anything new.`;
+}
+/**
+* Enforce the hard cap on an index before injection. Under the cap the index is
+* returned unchanged; over it, the index is truncated on a line boundary and a
+* notice is appended naming the true size so the agent knows entries are hidden
+* and must be pruned. This is the actual bound on injected context — callers
+* still report the true size via {@link indexSizeNote} so nothing is masked.
+*/
+function enforceMemoryIndexHardBudget(index) {
+	if (index.length <= 4e4) return index;
+	const clipped = index.slice(0, MEMORY_INDEX_HARD_BUDGET_CHARS);
+	const lastNewline = clipped.lastIndexOf("\n");
+	return `${lastNewline > 0 ? clipped.slice(0, lastNewline) : clipped}\n\n⚠️ Memory index truncated at ${MEMORY_INDEX_HARD_BUDGET_CHARS} chars (it is ${index.length}). Entries past this point are NOT shown. Prune the index now — delete stale entries and consolidate duplicates.`;
+}
+/**
+* Read the agent's hand-maintained shared index at `.memory/MEMORY.md`.
+* Returns the trimmed contents, or `null` when the file is absent or empty —
+* the agent owns this file, so we surface exactly what it wrote.
+*/
+async function readMemoryIndexFile({ cwd }) {
+	const path = join(cwd, MEMORY_DIRNAME, MEMORY_INDEX_FILENAME);
+	try {
+		const trimmed = (await readFile(path, "utf-8")).trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch {
+		return null;
+	}
+}
 const cache = /* @__PURE__ */ new Map();
 /**
+* Build the derived per-person index for a single user.
+*
 * Returns:
-* - `null` if `.memory/` doesn't exist
-* - `""` if the dir exists but contains nothing in the requested scope
+* - `null` if `.memory/users/` doesn't exist
+* - `""` if it exists but this user has no memory
 * - rendered markdown body (no surrounding header — caller wraps)
 *
-* The mtime-keyed cache stores the raw walked entries (the cost is the FS
-* walk); filtering by scope is cheap and runs per call, so two turns with
-* different scopes on the same cwd render correctly from one cached walk.
+* Scoping by id keeps one person's memory from bleeding into another's
+* conversation. The mtime-keyed cache stores the raw walked entries (the cost
+* is the FS walk); filtering by user is cheap and runs per call, so two turns
+* with different users on the same cwd render correctly from one cached walk.
 */
-async function buildMemoryIndex({ cwd, scope }) {
-	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
-	const maxMtimeMs = await maxMtimeAcrossDir(memoryDirAbs);
+async function buildMemoryIndex({ cwd, userId }) {
+	const usersDirAbs = join(cwd, MEMORY_DIRNAME, USERS_DIRNAME);
+	const maxMtimeMs = await maxMtimeAcrossDir(usersDirAbs);
 	if (maxMtimeMs === null) {
 		cache.delete(cwd);
 		return null;
@@ -2809,13 +2892,13 @@ async function buildMemoryIndex({ cwd, scope }) {
 	let cached = cache.get(cwd);
 	if (!cached || cached.builtAtMs < maxMtimeMs) {
 		cached = {
-			entries: await collectEntries(memoryDirAbs, cwd),
+			entries: await collectUserEntries(usersDirAbs, cwd),
 			builtAtMs: Date.now()
 		};
 		cache.set(cwd, cached);
 	}
-	const visible = cached.entries.filter((entry) => scope.kind === "user" ? entry.type === "users" && entry.subject?.startsWith(scope.userId) === true : entry.type !== "users");
-	return visible.length === 0 ? "" : renderIndex(visible);
+	const visible = cached.entries.filter((entry) => entry.subject.startsWith(userId));
+	return visible.length === 0 ? "" : renderUserIndex(visible);
 }
 async function maxMtimeAcrossDir(dir) {
 	let dirStat;
@@ -2863,45 +2946,22 @@ async function listSubdirs(dir) {
 	}
 	return entries.filter((e) => e.isDirectory()).map((e) => join(dir, e.name));
 }
-async function collectEntries(rootDirAbs, cwd) {
-	const collected = [];
-	await Promise.all(TYPE_DIRS.map(async (type) => {
-		const typeDirAbs = join(rootDirAbs, type);
-		if (TYPES_WITH_SUBJECT.has(type)) {
-			const subjectDirs = await listSubdirs(typeDirAbs);
-			await Promise.all(subjectDirs.map(async (subjectDirAbs) => {
-				const subject = basename(subjectDirAbs);
-				const files = await listMdFilesShallow(subjectDirAbs);
-				const parsed = await Promise.all(files.map(async (file) => {
-					const fm = await readFrontmatterOnly(file);
-					if (!fm?.name || !fm?.description) return null;
-					return {
-						name: fm.name,
-						description: fm.description,
-						type,
-						subject,
-						relPath: relative(cwd, file)
-					};
-				}));
-				for (const e of parsed) if (e) collected.push(e);
-			}));
-		} else {
-			const files = await listMdFilesShallow(typeDirAbs);
-			const parsed = await Promise.all(files.map(async (file) => {
-				const fm = await readFrontmatterOnly(file);
-				if (!fm?.name || !fm?.description) return null;
-				return {
-					name: fm.name,
-					description: fm.description,
-					type,
-					subject: null,
-					relPath: relative(cwd, file)
-				};
-			}));
-			for (const e of parsed) if (e) collected.push(e);
-		}
-	}));
-	return collected;
+async function collectUserEntries(usersDirAbs, cwd) {
+	const subjectDirs = await listSubdirs(usersDirAbs);
+	return (await Promise.all(subjectDirs.map(async (subjectDirAbs) => {
+		const subject = basename(subjectDirAbs);
+		const files = await listMdFilesShallow(subjectDirAbs);
+		return (await Promise.all(files.map(async (file) => {
+			const fm = await readFrontmatterOnly(file);
+			if (!fm?.name || !fm?.description) return null;
+			return {
+				name: fm.name,
+				description: fm.description,
+				subject,
+				relPath: relative(cwd, file)
+			};
+		}))).filter((e) => e !== null);
+	}))).flat();
 }
 async function readFrontmatterOnly(filePath) {
 	let fh;
@@ -2932,68 +2992,180 @@ function parseFrontmatter(text) {
 	const result = FrontmatterSchema.safeParse(parsed);
 	return result.success ? result.data : null;
 }
-function renderIndex(entries) {
-	const byType = {
-		users: [],
-		projects: [],
-		feedback: [],
-		reference: []
-	};
-	for (const e of entries) byType[e.type].push(e);
+function renderUserIndex(entries) {
+	const bySubject = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const list = bySubject.get(e.subject) ?? [];
+		list.push(e);
+		bySubject.set(e.subject, list);
+	}
+	const lines = ["### Users"];
+	for (const subject of [...bySubject.keys()].sort()) {
+		lines.push(`- **${subject}**`);
+		for (const e of bySubject.get(subject) ?? []) lines.push(`  - \`${e.relPath}\` — ${e.description}`);
+	}
+	return lines.join("\n");
+}
+/**
+* One-time migration for agents created before `MEMORY.md` existed. If there is
+* no hand-maintained `.memory/MEMORY.md` yet but the agent has shared memory
+* files from the old frontmatter-indexed layout (`projects/`, `feedback/`,
+* `reference/`), derive a `MEMORY.md` from their frontmatter and write it once.
+* After that the agent owns the file — this never runs again for that agent and
+* never clobbers an existing index.
+*
+* Returns the seeded contents (also written to disk), or `null` when nothing
+* was seeded (index already present, or no legacy shared files). A write
+* failure propagates so the caller can log it; the read path then falls back to
+* whatever is on disk.
+*/
+async function seedMemoryIndexFile({ cwd }) {
+	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
+	const indexPath = join(memoryDirAbs, MEMORY_INDEX_FILENAME);
+	if (await stat(indexPath).catch(() => null)) return null;
+	const perType = await Promise.all(LEGACY_SHARED_TYPES.map(async ({ dir, label }) => {
+		const typeDirAbs = join(memoryDirAbs, dir);
+		const files = [];
+		await walkMdFiles(typeDirAbs, files);
+		return {
+			label,
+			entries: (await Promise.all(files.map(async (file) => {
+				const fm = await readFrontmatterOnly(file);
+				if (!fm?.name || !fm?.description) return null;
+				return {
+					name: fm.name,
+					description: fm.description,
+					relPath: relative(cwd, file)
+				};
+			}))).filter((e) => !!e)
+		};
+	}));
+	if (perType.every((group) => group.entries.length === 0)) return null;
+	const content = renderSeededIndex(perType);
+	await writeFile(indexPath, `${content}\n`, "utf-8");
+	return content;
+}
+function renderSeededIndex(groups) {
 	const sections = [];
-	for (const type of TYPE_DIRS) {
-		const items = byType[type];
-		if (items.length === 0) continue;
-		sections.push(`### ${TYPE_LABELS[type]}`);
-		if (TYPES_WITH_SUBJECT.has(type)) {
-			const bySubject = /* @__PURE__ */ new Map();
-			for (const e of items) {
-				const subject = e.subject ?? "(unknown)";
-				const list = bySubject.get(subject) ?? [];
-				list.push(e);
-				bySubject.set(subject, list);
-			}
-			const subjects = [...bySubject.keys()].sort();
-			for (const subject of subjects) {
-				sections.push(`- **${subject}**`);
-				for (const e of bySubject.get(subject) ?? []) sections.push(`  - \`${e.relPath}\` — ${e.description}`);
-			}
-		} else for (const e of items) sections.push(`- \`${e.relPath}\` — ${e.description}`);
+	for (const { label, entries } of groups) {
+		if (entries.length === 0) continue;
+		sections.push(`### ${label}`);
+		const sorted = [...entries].sort((a, b) => a.relPath.localeCompare(b.relPath));
+		for (const e of sorted) sections.push(`- [${e.name}](${e.relPath}) — ${e.description}`);
 		sections.push("");
 	}
 	return sections.join("\n").trimEnd();
 }
+/**
+* The version at which the hand-maintained `MEMORY.md` layout was introduced.
+* Used to classify an unversioned `.memory/`: if it already has a `MEMORY.md`
+* it's on this layout (not the pre-MEMORY.md v1 frontmatter layout), so it
+* shouldn't be treated as v1 and re-seeded.
+*/
+const HAND_MAINTAINED_INDEX_VERSION = 2;
+const VERSION_FILENAME = ".version";
+const MEMORY_MIGRATIONS = [{
+	from: 1,
+	to: 2,
+	apply: async ({ cwd }) => {
+		await seedMemoryIndexFile({ cwd });
+	}
+}];
+/**
+* The layout version of an agent's `.memory/`:
+* - `null` when there's no `.memory/` at all (a fresh agent is current by
+*   construction; nothing to migrate).
+* - `1` when `.memory/` exists but carries no `.version` marker — i.e. it
+*   predates versioning.
+* - otherwise the integer in `.memory/.version`.
+*/
+async function readMemoryVersion(cwd) {
+	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
+	if (!(await stat(memoryDirAbs).catch(() => null))?.isDirectory()) return null;
+	const raw = await readFile(join(memoryDirAbs, VERSION_FILENAME), "utf-8").catch(() => null);
+	if (raw === null) return await stat(join(memoryDirAbs, MEMORY_INDEX_FILENAME)).then((s) => s.isFile()).catch(() => false) ? HAND_MAINTAINED_INDEX_VERSION : 1;
+	const parsed = Number.parseInt(raw.trim(), 10);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
+}
+async function writeMemoryVersion(cwd, version) {
+	await writeFile(join(cwd, MEMORY_DIRNAME, VERSION_FILENAME), `${version}\n`, "utf-8");
+}
+/**
+* Bring an agent's `.memory/` up to `CURRENT_MEMORY_VERSION` by applying the
+* ordered migrations. Runs on session start. No-op when there's no `.memory/`
+* yet or it's already current. Migrations must be idempotent, so a lost/unwritten
+* version marker (the file isn't committed by the harness) only costs a repeated
+* no-op, never corruption. Returns the `{ from, to }` actually applied, or
+* `null` when nothing ran.
+*/
+async function migrateMemory({ cwd }) {
+	const from = await readMemoryVersion(cwd);
+	if (from === null || from >= 2) return null;
+	let version = from;
+	while (version < 2) {
+		const migration = MEMORY_MIGRATIONS.find((m) => m.from === version);
+		if (!migration) break;
+		await migration.apply({ cwd });
+		version = migration.to;
+	}
+	await writeMemoryVersion(cwd, version);
+	return {
+		from,
+		to: version
+	};
+}
 //#endregion
 //#region src/extensions/memory.ts
 const log$6 = logger.child({ module: "memory-extension" });
 /**
 * The standing instructions for the memory system. Always injected (even with
-* an empty `.memory/`) so the agent knows it can persist notes. `users/` is
+* no `MEMORY.md`) so the agent knows it can persist notes and how. `users/` is
 * described by the platform memory extension, which is the only thing that can
 * scope it to a person — here we just point at it.
 */
 function memoryInstructions(cwd) {
 	return `## Memory across conversations
 
-Persistent notes across conversations live at \`${cwd}/.memory/\` — plain markdown files in your repo. The harness builds and injects an **index** of these files (paths + one-line descriptions) into your system prompt every turn; **bodies are NOT auto-loaded** — when an index entry looks relevant, use your \`read\` tool to load that specific file.
+Persistent notes across conversations live at \`${cwd}/.memory/\` — plain markdown files in your repo, one fact per file. You maintain a hand-written index of them at \`${cwd}/.memory/MEMORY.md\`, and the harness injects that index into your system prompt every turn. **Bodies are NOT auto-loaded** — when an index line looks relevant, use your \`read\` tool to load that specific file.
 
 Memory records **what happened**: facts you learned, events, investigation findings, project and system details worth carrying forward. It is NOT where behavior goes. A standing rule about how you should act — a "from now on, always/never …", a tone or format preference, a workflow convention a user wants you to follow — belongs in \`soul.md\` (see the Persona / Standing instructions section), not here. When a note is really an instruction about your behavior, write it to \`soul.md\`; when it is a fact or a record of something that occurred, write it here.
 
-Shared knowledge is laid out as \`projects/<slug>/<topic>.md\` for project and system context, \`feedback/<topic>.md\` for concrete lessons learned from something that happened (the event and what it taught you — not a free-floating rule; the rule itself, if durable, goes in \`soul.md\`), and \`reference/<topic>.md\` for how external systems work. (Notes about a specific person live under \`users/\` and are shown separately, scoped to whoever you're talking to.) Each file's frontmatter declares \`name\` and \`description\` (the description is what shows up in the index, so make it a one-line behavior-triggering hook). Commit and push after writing to persist it.`;
+You own \`MEMORY.md\`. When you learn something durable, write the fact to its own \`.md\` file and add a one-line pointer to \`MEMORY.md\` in the form \`- [Title](relative/path.md) — one-line hook\`, where the hook is what tells future-you when to open the file. \`MEMORY.md\` is an *index*, never a store — put the actual content in the topic file and only a pointer line in \`MEMORY.md\`; do not inline a fact's body into the index even when it seems cheaper. Start each topic file with \`name:\`/\`description:\` frontmatter (the \`description\` is the one-line hook) so the index can be re-seeded, re-derived, or linted from the files themselves. When a fact changes, edit both the file and its line; when it stops being true, delete the file and its line. Shared knowledge is laid out as \`projects/<slug>/<topic>.md\` for project and system context, \`feedback/<topic>.md\` for concrete lessons learned from something that happened (the event and what it taught you — not a free-floating rule; the rule itself, if durable, goes in \`soul.md\`), and \`reference/<topic>.md\` for how external systems work. (Notes about a specific person live under \`users/\` and are indexed for you separately, scoped to whoever you're talking to — don't put people's private notes in the shared \`MEMORY.md\`.)
+
+Keep \`MEMORY.md\` lean. It's re-injected on *every* turn, so a small, high-signal index is worth far more than an exhaustive one — curate it like a tightly-edited table of contents, not a log:
+- Be selective. Only record something durable that will matter in a *future* conversation. Don't record what only matters right now, what you can re-derive on demand, or what's already obvious from the repo.
+- Consolidate before you create. Before adding a line, scan \`MEMORY.md\` for one that already covers the topic; if it exists, \`read\` that file and rewrite it with the new facts merged in rather than adding a near-duplicate. One fact per file, but don't fragment a topic across many thin files.
+- Prune as you go. Delete lines (and their files) that are wrong, stale, or superseded. The index header reports its size — when it's flagged over budget, consolidate and delete before adding anything new.
+- Write dates absolute, not relative. Resolve "last week" / "yesterday" to a concrete date when you record it (e.g. "on 7/3 Dhruv told me to …"), so the note still reads correctly in a future conversation.
+
+Commit and push after editing \`.memory/\` to persist it.`;
 }
 function composeBlock$1({ cwd, index }) {
 	const instructions = memoryInstructions(cwd);
 	if (!index || index.length === 0) return instructions;
-	return `${instructions}\n\n## Memory index\n\n${index}`;
+	const header = `## Memory index (${indexSizeNote(index)})`;
+	const warning = indexBudgetWarning(index);
+	const rendered = enforceMemoryIndexHardBudget(index);
+	return `${instructions}\n\n${warning ? `${header}\n\n${warning}\n\n${rendered}` : `${header}\n\n${rendered}`}`;
 }
 const memoryExtension = (pi) => {
 	let cachedBlock = null;
 	pi.on("session_start", async (_event, ctx) => {
 		try {
-			const index = await buildMemoryIndex({
-				cwd: ctx.cwd,
-				scope: { kind: "shared" }
-			});
+			const migrated = await migrateMemory({ cwd: ctx.cwd });
+			if (migrated !== null) log$6.info({
+				event: "memory_migrated",
+				from: migrated.from,
+				to: migrated.to
+			}, "migrated memory layout to current version");
+		} catch (err) {
+			log$6.warn({
+				err,
+				event: "memory_migration_failed"
+			}, "memory migration failed; continuing with existing index");
+		}
+		try {
+			const index = await readMemoryIndexFile({ cwd: ctx.cwd });
 			cachedBlock = composeBlock$1({
 				cwd: ctx.cwd,
 				index
@@ -3002,7 +3174,7 @@ const memoryExtension = (pi) => {
 			log$6.warn({
 				err,
 				event: "memory_index_failed"
-			}, "memory index build failed; injecting instructions only");
+			}, "memory index read failed; injecting instructions only");
 			cachedBlock = memoryInstructions(ctx.cwd);
 		}
 	});
@@ -3061,9 +3233,12 @@ function slugifyName(name) {
 function composeBlock({ index, user }) {
 	const instructions = `## Current user memory
 
-Notes about the person on this turn — the only \`users/\` memory you can see. Store anything you learn about them under \`${`.memory/users/${user.id}-${slugifyName(user.displayName)}/`}<topic>.md\`, using exactly this directory. Other people's \`users/\` notes are never shown, so never address someone by a name you only find in memory.`;
+Notes about the person on this turn — the only \`users/\` memory you can see. Store anything you learn about them under \`${`.memory/users/${user.id}-${slugifyName(user.displayName)}/`}<topic>.md\`, using exactly this directory. Other people's \`users/\` notes are never shown, so never address someone by a name you only find in memory. Keep it lean and be selective — this is re-injected every turn; consolidate related facts into one file and delete what's stale rather than piling on near-duplicates.`;
 	if (!index || index.length === 0) return instructions;
-	return `${instructions}\n\n${index}`;
+	const warning = indexBudgetWarning(index);
+	const header = `Memory index (${indexSizeNote(index)}):`;
+	const rendered = enforceMemoryIndexHardBudget(index);
+	return `${instructions}\n\n${warning ? `${warning}\n\n${header}\n\n${rendered}` : `${header}\n\n${rendered}`}`;
 }
 /**
 * Build the platform memory extension. `channelContext` is the per-turn ref
@@ -3084,10 +3259,7 @@ function createPlatformMemoryExtension({ channelContext }) {
 				cachedBlock = composeBlock({
 					index: await buildMemoryIndex({
 						cwd: ctx.cwd,
-						scope: {
-							kind: "user",
-							userId: user.id
-						}
+						userId: user.id
 					}),
 					user
 				});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skydiveai/pi-extensions",
-  "version": "0.1.0-beta.1565",
+  "version": "0.1.0-beta.1569",
   "homepage": "https://skydive.com",
   "license": "MIT",
   "author": "Create, Inc.",