pi-memory 0.2.2

package/index.ts

@@ -0,0 +1,1099 @@
+/**
+ * Memory Extension with QMD-Powered Search
+ *
+ * Plain-Markdown memory system with semantic search via qmd.
+ * Core memory tools (write/read/scratchpad) work without qmd installed.
+ * The memory_search tool requires qmd for keyword, semantic, and hybrid search.
+ *
+ * Layout (under ~/.pi/agent/memory/):
+ *   MEMORY.md              — curated long-term memory (decisions, preferences, durable facts)
+ *   SCRATCHPAD.md           — checklist of things to keep in mind / fix later
+ *   daily/YYYY-MM-DD.md    — daily append-only log (today + yesterday loaded at session start)
+ *
+ * Tools:
+ *   memory_write   — write to MEMORY.md or daily log
+ *   memory_read    — read any memory file or list daily logs
+ *   scratchpad     — add/check/uncheck/clear items on the scratchpad checklist
+ *   memory_search  — search across all memory files via qmd (keyword, semantic, or deep)
+ *
+ * Context injection:
+ *   - MEMORY.md + SCRATCHPAD.md + today's + yesterday's daily logs injected into every turn
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Paths (mutable for testing via _setBaseDir / _resetBaseDir)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MEMORY_DIR = path.join(process.env.HOME ?? "~", ".pi", "agent", "memory");
+
+let MEMORY_DIR = DEFAULT_MEMORY_DIR;
+let MEMORY_FILE = path.join(MEMORY_DIR, "MEMORY.md");
+let SCRATCHPAD_FILE = path.join(MEMORY_DIR, "SCRATCHPAD.md");
+let DAILY_DIR = path.join(MEMORY_DIR, "daily");
+
+/** Override base directory (for testing). */
+export function _setBaseDir(baseDir: string) {
+	MEMORY_DIR = baseDir;
+	MEMORY_FILE = path.join(baseDir, "MEMORY.md");
+	SCRATCHPAD_FILE = path.join(baseDir, "SCRATCHPAD.md");
+	DAILY_DIR = path.join(baseDir, "daily");
+}
+
+/** Reset to default paths (for testing). */
+export function _resetBaseDir() {
+	_setBaseDir(DEFAULT_MEMORY_DIR);
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+export function ensureDirs() {
+	fs.mkdirSync(MEMORY_DIR, { recursive: true });
+	fs.mkdirSync(DAILY_DIR, { recursive: true });
+}
+
+export function todayStr(): string {
+	const d = new Date();
+	return d.toISOString().slice(0, 10);
+}
+
+export function yesterdayStr(): string {
+	const d = new Date();
+	d.setDate(d.getDate() - 1);
+	return d.toISOString().slice(0, 10);
+}
+
+export function nowTimestamp(): string {
+	return new Date().toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+}
+
+export function shortSessionId(sessionId: string): string {
+	return sessionId.slice(0, 8);
+}
+
+export function readFileSafe(filePath: string): string | null {
+	try {
+		return fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+export function dailyPath(date: string): string {
+	return path.join(DAILY_DIR, `${date}.md`);
+}
+
+// ---------------------------------------------------------------------------
+// Limits + preview helpers
+// ---------------------------------------------------------------------------
+
+const RESPONSE_PREVIEW_MAX_CHARS = 4_000;
+const RESPONSE_PREVIEW_MAX_LINES = 120;
+
+const CONTEXT_LONG_TERM_MAX_CHARS = 4_000;
+const CONTEXT_LONG_TERM_MAX_LINES = 150;
+const CONTEXT_SCRATCHPAD_MAX_CHARS = 2_000;
+const CONTEXT_SCRATCHPAD_MAX_LINES = 120;
+const CONTEXT_DAILY_MAX_CHARS = 3_000;
+const CONTEXT_DAILY_MAX_LINES = 120;
+const CONTEXT_SEARCH_MAX_CHARS = 2_500;
+const CONTEXT_SEARCH_MAX_LINES = 80;
+const CONTEXT_MAX_CHARS = 16_000;
+
+type TruncateMode = "start" | "end" | "middle";
+
+interface PreviewResult {
+	preview: string;
+	truncated: boolean;
+	totalLines: number;
+	totalChars: number;
+	previewLines: number;
+	previewChars: number;
+}
+
+function normalizeContent(content: string): string {
+	return content.trim();
+}
+
+function truncateLines(lines: string[], maxLines: number, mode: TruncateMode) {
+	if (maxLines <= 0 || lines.length <= maxLines) {
+		return { lines, truncated: false };
+	}
+
+	if (mode === "end") {
+		return { lines: lines.slice(-maxLines), truncated: true };
+	}
+
+	if (mode === "middle" && maxLines > 1) {
+		const marker = "... (truncated) ...";
+		const keep = maxLines - 1;
+		const headCount = Math.ceil(keep / 2);
+		const tailCount = Math.floor(keep / 2);
+		const head = lines.slice(0, headCount);
+		const tail = tailCount > 0 ? lines.slice(-tailCount) : [];
+		return { lines: [...head, marker, ...tail], truncated: true };
+	}
+
+	return { lines: lines.slice(0, maxLines), truncated: true };
+}
+
+function truncateText(text: string, maxChars: number, mode: TruncateMode) {
+	if (maxChars <= 0 || text.length <= maxChars) {
+		return { text, truncated: false };
+	}
+
+	if (mode === "end") {
+		return { text: text.slice(-maxChars), truncated: true };
+	}
+
+	if (mode === "middle" && maxChars > 10) {
+		const marker = "... (truncated) ...";
+		const keep = maxChars - marker.length;
+		if (keep > 0) {
+			const headCount = Math.ceil(keep / 2);
+			const tailCount = Math.floor(keep / 2);
+			return {
+				text: text.slice(0, headCount) + marker + text.slice(text.length - tailCount),
+				truncated: true,
+			};
+		}
+	}
+
+	return { text: text.slice(0, maxChars), truncated: true };
+}
+
+function buildPreview(content: string, options: { maxLines: number; maxChars: number; mode: TruncateMode }): PreviewResult {
+	const normalized = normalizeContent(content);
+	if (!normalized) {
+		return { preview: "", truncated: false, totalLines: 0, totalChars: 0, previewLines: 0, previewChars: 0 };
+	}
+
+	const lines = normalized.split("\n");
+	const totalLines = lines.length;
+	const totalChars = normalized.length;
+
+	const lineResult = truncateLines(lines, options.maxLines, options.mode);
+	const text = lineResult.lines.join("\n");
+	const charResult = truncateText(text, options.maxChars, options.mode);
+	const preview = charResult.text;
+
+	const previewLines = preview ? preview.split("\n").length : 0;
+	const previewChars = preview.length;
+
+	return {
+		preview,
+		truncated: lineResult.truncated || charResult.truncated,
+		totalLines,
+		totalChars,
+		previewLines,
+		previewChars,
+	};
+}
+
+function formatPreviewBlock(label: string, content: string, mode: TruncateMode) {
+	const result = buildPreview(content, {
+		maxLines: RESPONSE_PREVIEW_MAX_LINES,
+		maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+		mode,
+	});
+
+	if (!result.preview) {
+		return `${label}: empty.`;
+	}
+
+	const meta = `${label} (${result.totalLines} lines, ${result.totalChars} chars)`;
+	const note = result.truncated
+		? `\n[preview truncated: showing ${result.previewLines}/${result.totalLines} lines, ${result.previewChars}/${result.totalChars} chars]`
+		: "";
+	return `${meta}\n\n${result.preview}${note}`;
+}
+
+function formatContextSection(label: string, content: string, mode: TruncateMode, maxLines: number, maxChars: number) {
+	const result = buildPreview(content, { maxLines, maxChars, mode });
+	if (!result.preview) {
+		return "";
+	}
+	const note = result.truncated
+		? `\n\n[truncated: showing ${result.previewLines}/${result.totalLines} lines, ${result.previewChars}/${result.totalChars} chars]`
+		: "";
+	return `${label}\n\n${result.preview}${note}`;
+}
+
+function getQmdUpdateMode(): "background" | "manual" | "off" {
+	const mode = (process.env.PI_MEMORY_QMD_UPDATE ?? "background").toLowerCase();
+	if (mode === "manual" || mode === "off" || mode === "background") {
+		return mode;
+	}
+	return "background";
+}
+
+async function ensureQmdAvailableForUpdate(): Promise<boolean> {
+	if (qmdAvailable) return true;
+	if (getQmdUpdateMode() !== "background") return false;
+	qmdAvailable = await detectQmd();
+	return qmdAvailable;
+}
+
+// ---------------------------------------------------------------------------
+// Scratchpad helpers
+// ---------------------------------------------------------------------------
+
+export interface ScratchpadItem {
+	done: boolean;
+	text: string;
+	meta: string; // the <!-- timestamp [session] --> comment
+}
+
+export function parseScratchpad(content: string): ScratchpadItem[] {
+	const items: ScratchpadItem[] = [];
+	const lines = content.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const match = line.match(/^- \[([ xX])\] (.+)$/);
+		if (match) {
+			let meta = "";
+			if (i > 0 && lines[i - 1].match(/^<!--.*-->$/)) {
+				meta = lines[i - 1];
+			}
+			items.push({
+				done: match[1].toLowerCase() === "x",
+				text: match[2],
+				meta,
+			});
+		}
+	}
+	return items;
+}
+
+export function serializeScratchpad(items: ScratchpadItem[]): string {
+	const lines: string[] = ["# Scratchpad", ""];
+	for (const item of items) {
+		if (item.meta) {
+			lines.push(item.meta);
+		}
+		const checkbox = item.done ? "[x]" : "[ ]";
+		lines.push(`- ${checkbox} ${item.text}`);
+	}
+	return lines.join("\n") + "\n";
+}
+
+// ---------------------------------------------------------------------------
+// Context builder
+// ---------------------------------------------------------------------------
+
+export function buildMemoryContext(searchResults?: string): string {
+	ensureDirs();
+	// Priority order: scratchpad > today's daily > search results > MEMORY.md > yesterday's daily
+	const sections: string[] = [];
+
+	const scratchpad = readFileSafe(SCRATCHPAD_FILE);
+	if (scratchpad?.trim()) {
+		const openItems = parseScratchpad(scratchpad).filter((i) => !i.done);
+		if (openItems.length > 0) {
+			const serialized = serializeScratchpad(openItems);
+			const section = formatContextSection(
+				"## SCRATCHPAD.md (working context)",
+				serialized,
+				"start",
+				CONTEXT_SCRATCHPAD_MAX_LINES,
+				CONTEXT_SCRATCHPAD_MAX_CHARS,
+			);
+			if (section) sections.push(section);
+		}
+	}
+
+	const today = todayStr();
+	const yesterday = yesterdayStr();
+
+	const todayContent = readFileSafe(dailyPath(today));
+	if (todayContent?.trim()) {
+		const section = formatContextSection(
+			`## Daily log: ${today} (today)`,
+			todayContent,
+			"end",
+			CONTEXT_DAILY_MAX_LINES,
+			CONTEXT_DAILY_MAX_CHARS,
+		);
+		if (section) sections.push(section);
+	}
+
+	if (searchResults?.trim()) {
+		const section = formatContextSection(
+			"## Relevant memories (auto-retrieved)",
+			searchResults,
+			"start",
+			CONTEXT_SEARCH_MAX_LINES,
+			CONTEXT_SEARCH_MAX_CHARS,
+		);
+		if (section) sections.push(section);
+	}
+
+	const longTerm = readFileSafe(MEMORY_FILE);
+	if (longTerm?.trim()) {
+		const section = formatContextSection(
+			"## MEMORY.md (long-term)",
+			longTerm,
+			"middle",
+			CONTEXT_LONG_TERM_MAX_LINES,
+			CONTEXT_LONG_TERM_MAX_CHARS,
+		);
+		if (section) sections.push(section);
+	}
+
+	const yesterdayContent = readFileSafe(dailyPath(yesterday));
+	if (yesterdayContent?.trim()) {
+		const section = formatContextSection(
+			`## Daily log: ${yesterday} (yesterday)`,
+			yesterdayContent,
+			"end",
+			CONTEXT_DAILY_MAX_LINES,
+			CONTEXT_DAILY_MAX_CHARS,
+		);
+		if (section) sections.push(section);
+	}
+
+	if (sections.length === 0) {
+		return "";
+	}
+
+	const context = `# Memory\n\n${sections.join("\n\n---\n\n")}`;
+	if (context.length > CONTEXT_MAX_CHARS) {
+		const result = buildPreview(context, {
+			maxLines: Number.POSITIVE_INFINITY,
+			maxChars: CONTEXT_MAX_CHARS,
+			mode: "start",
+		});
+		const note = result.truncated
+			? `\n\n[truncated overall context: showing ${result.previewChars}/${result.totalChars} chars]`
+			: "";
+		return `${result.preview}${note}`;
+	}
+
+	return context;
+}
+
+// ---------------------------------------------------------------------------
+// QMD integration
+// ---------------------------------------------------------------------------
+
+let qmdAvailable = false;
+let updateTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Set qmd availability flag (for testing). */
+export function _setQmdAvailable(value: boolean) {
+	qmdAvailable = value;
+}
+
+/** Get current qmd availability flag (for testing). */
+export function _getQmdAvailable(): boolean {
+	return qmdAvailable;
+}
+
+/** Get current update timer (for testing). */
+export function _getUpdateTimer(): ReturnType<typeof setTimeout> | null {
+	return updateTimer;
+}
+
+/** Clear the update timer (for testing). */
+export function _clearUpdateTimer() {
+	if (updateTimer) {
+		clearTimeout(updateTimer);
+		updateTimer = null;
+	}
+}
+
+const QMD_REPO_URL = "https://github.com/tobi/qmd";
+
+export function qmdInstallInstructions(): string {
+	return [
+		"memory_search requires qmd.",
+		"",
+		"Install qmd (requires Bun):",
+		`  bun install -g ${QMD_REPO_URL}`,
+		"  # ensure ~/.bun/bin is in your PATH",
+		"",
+		"Then set up the collection (one-time):",
+		`  qmd collection add ${MEMORY_DIR} --name pi-memory`,
+		"  qmd embed",
+	].join("\n");
+}
+
+/** Auto-create the pi-memory collection and path contexts in qmd. */
+export async function setupQmdCollection(): Promise<boolean> {
+	try {
+		await new Promise<void>((resolve, reject) => {
+			execFile(
+				"qmd",
+				["collection", "add", MEMORY_DIR, "--name", "pi-memory"],
+				{ timeout: 10_000 },
+				(err) => (err ? reject(err) : resolve()),
+			);
+		});
+	} catch {
+		// Collection may already exist under a different name — not critical
+		return false;
+	}
+
+	// Add path contexts (best-effort, ignore errors)
+	const contexts: [string, string][] = [
+		["/daily", "Daily append-only work logs organized by date"],
+		["/", "Curated long-term memory: decisions, preferences, facts, lessons"],
+	];
+	for (const [ctxPath, desc] of contexts) {
+		try {
+			await new Promise<void>((resolve, reject) => {
+				execFile(
+					"qmd",
+					["context", "add", ctxPath, desc, "-c", "pi-memory"],
+					{ timeout: 10_000 },
+					(err) => (err ? reject(err) : resolve()),
+				);
+			});
+		} catch {
+			// Ignore — context may already exist
+		}
+	}
+	return true;
+}
+
+export function detectQmd(): Promise<boolean> {
+	return new Promise((resolve) => {
+		// qmd doesn't reliably support --version; use a fast command that exits 0 when available.
+		execFile("qmd", ["status"], { timeout: 5_000 }, (err) => {
+			resolve(!err);
+		});
+	});
+}
+
+export function checkCollection(name: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		execFile("qmd", ["collection", "list", "--json"], { timeout: 10_000 }, (err, stdout) => {
+			if (err) {
+				resolve(false);
+				return;
+			}
+			try {
+				const collections = JSON.parse(stdout);
+				if (Array.isArray(collections)) {
+					resolve(collections.some((c: any) => c.name === name || c === name));
+				} else {
+					// qmd may output an object with a collections array or similar
+					resolve(stdout.includes(name));
+				}
+			} catch {
+				// Fallback: just check if the name appears in the output
+				resolve(stdout.includes(name));
+			}
+		});
+	});
+}
+
+export function scheduleQmdUpdate() {
+	if (getQmdUpdateMode() !== "background") return;
+	if (!qmdAvailable) return;
+	if (updateTimer) clearTimeout(updateTimer);
+	updateTimer = setTimeout(() => {
+		updateTimer = null;
+		execFile("qmd", ["update"], { timeout: 30_000 }, () => {});
+	}, 500);
+}
+
+/** Search for memories relevant to the user's prompt. Returns formatted markdown or empty string on error. */
+export async function searchRelevantMemories(prompt: string): Promise<string> {
+	if (!qmdAvailable || !prompt.trim()) return "";
+
+	// Sanitize: strip control chars, limit to 200 chars for the search query
+	// eslint-disable-next-line no-control-regex
+	const sanitized = prompt.replace(/[\x00-\x1f\x7f]/g, " ").trim().slice(0, 200);
+	if (!sanitized) return "";
+
+	try {
+		const hasCollection = await checkCollection("pi-memory");
+		if (!hasCollection) return "";
+
+		const results = await Promise.race([
+			runQmdSearch("keyword", sanitized, 3),
+			new Promise<never>((_, reject) => setTimeout(() => reject(new Error("timeout")), 3_000)),
+		]);
+
+		if (!results || results.length === 0) return "";
+
+		const snippets = results
+			.map((r) => {
+				const text = r.content ?? r.chunk ?? "";
+				if (!text.trim()) return null;
+				const filePart = r.path ? `_${r.path}_` : "";
+				return `${filePart}\n${text.trim()}`;
+			})
+			.filter(Boolean);
+
+		if (snippets.length === 0) return "";
+		return snippets.join("\n\n---\n\n");
+	} catch {
+		return "";
+	}
+}
+
+export interface QmdSearchResult {
+	path?: string;
+	score?: number;
+	content?: string;
+	chunk?: string;
+	title?: string;
+	[key: string]: unknown;
+}
+
+export function runQmdSearch(
+	mode: "keyword" | "semantic" | "deep",
+	query: string,
+	limit: number,
+): Promise<QmdSearchResult[]> {
+	const subcommand = mode === "keyword" ? "search" : mode === "semantic" ? "vsearch" : "query";
+	const args = [subcommand, "--json", "-c", "pi-memory", "-n", String(limit), query];
+
+	return new Promise((resolve, reject) => {
+		execFile("qmd", args, { timeout: 60_000 }, (err, stdout, stderr) => {
+			if (err) {
+				reject(new Error(stderr?.trim() || err.message));
+				return;
+			}
+			try {
+				const parsed = JSON.parse(stdout);
+				const results = Array.isArray(parsed) ? parsed : parsed.results ?? parsed.hits ?? [];
+				resolve(results);
+			} catch {
+				reject(new Error(`Failed to parse qmd output: ${stdout.slice(0, 200)}`));
+			}
+		});
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+	// --- session_start: detect qmd, auto-setup collection ---
+	pi.on("session_start", async (_event, ctx) => {
+		qmdAvailable = await detectQmd();
+		if (!qmdAvailable) {
+			if (ctx.hasUI) {
+				ctx.ui.notify(qmdInstallInstructions(), "info");
+			}
+			return;
+		}
+
+		const hasCollection = await checkCollection("pi-memory");
+		if (!hasCollection) {
+			await setupQmdCollection();
+		}
+	});
+
+	// --- session_shutdown: clean up timer ---
+	pi.on("session_shutdown", async () => {
+		if (updateTimer) {
+			clearTimeout(updateTimer);
+			updateTimer = null;
+		}
+	});
+
+	// --- Inject memory context before every agent turn ---
+	pi.on("before_agent_start", async (event, _ctx) => {
+		const skipSearch = process.env.PI_MEMORY_NO_SEARCH === "1";
+		const searchResults = skipSearch ? "" : await searchRelevantMemories(event.prompt ?? "");
+		const memoryContext = buildMemoryContext(searchResults);
+		if (!memoryContext) return;
+
+		const memoryInstructions = [
+			"\n\n## Memory",
+			"The following memory files have been loaded. Use the memory_write tool to persist important information.",
+			"- Decisions, preferences, and durable facts \u2192 MEMORY.md",
+			"- Day-to-day notes and running context \u2192 daily/<YYYY-MM-DD>.md",
+			"- Things to fix later or keep in mind \u2192 scratchpad tool",
+			"- Use memory_search to find past context across all memory files (keyword, semantic, or deep search).",
+			"- Use #tags (e.g. #decision, #preference) and [[links]] (e.g. [[auth-strategy]]) in memory content to improve future search recall.",
+			"- If someone says \"remember this,\" write it immediately.",
+			"",
+			memoryContext,
+		].join("\n");
+
+		return {
+			systemPrompt: event.systemPrompt + memoryInstructions,
+		};
+	});
+
+	// --- Pre-compaction: auto-capture session handoff ---
+	pi.on("session_before_compact", async (_event, ctx) => {
+		ensureDirs();
+		const sid = shortSessionId(ctx.sessionManager.getSessionId());
+		const ts = nowTimestamp();
+		const parts: string[] = [];
+
+		// Capture open scratchpad items
+		const scratchpad = readFileSafe(SCRATCHPAD_FILE);
+		if (scratchpad?.trim()) {
+			const openItems = parseScratchpad(scratchpad).filter((i) => !i.done);
+			if (openItems.length > 0) {
+				parts.push("**Open scratchpad items:**");
+				for (const item of openItems) {
+					parts.push(`- [ ] ${item.text}`);
+				}
+			}
+		}
+
+		// Capture last few lines from today's daily log
+		const todayContent = readFileSafe(dailyPath(todayStr()));
+		if (todayContent?.trim()) {
+			const lines = todayContent.trim().split("\n");
+			const tail = lines.slice(-15).join("\n");
+			parts.push(`**Recent daily log context:**\n${tail}`);
+		}
+
+		if (parts.length === 0) return;
+
+		const handoff = [
+			`<!-- HANDOFF ${ts} [${sid}] -->`,
+			"## Session Handoff",
+			...parts,
+		].join("\n");
+
+		const filePath = dailyPath(todayStr());
+		const existing = readFileSafe(filePath) ?? "";
+		const separator = existing.trim() ? "\n\n" : "";
+		fs.writeFileSync(filePath, existing + separator + handoff, "utf-8");
+		await ensureQmdAvailableForUpdate();
+		scheduleQmdUpdate();
+	});
+
+	// --- memory_write tool ---
+	pi.registerTool({
+		name: "memory_write",
+		label: "Memory Write",
+		description: [
+			"Write to memory files. Two targets:",
+			"- 'long_term': Write to MEMORY.md (curated durable facts, decisions, preferences). Mode: 'append' or 'overwrite'.",
+			"- 'daily': Append to today's daily log (daily/<YYYY-MM-DD>.md). Always appends.",
+			"Use this when the user asks you to remember something, or when you learn important preferences/decisions.",
+			"Use #tags (e.g. #decision, #preference, #lesson, #bug) and [[links]] (e.g. [[auth-strategy]]) in content to improve searchability.",
+		].join("\n"),
+		parameters: Type.Object({
+			target: StringEnum(["long_term", "daily"] as const, {
+				description: "Where to write: 'long_term' for MEMORY.md, 'daily' for today's daily log",
+			}),
+			content: Type.String({ description: "Content to write (Markdown)" }),
+			mode: Type.Optional(
+				StringEnum(["append", "overwrite"] as const, {
+					description: "Write mode for long_term target. Default: 'append'. Daily always appends.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			ensureDirs();
+			const { target, content, mode } = params;
+			const sid = shortSessionId(ctx.sessionManager.getSessionId());
+			const ts = nowTimestamp();
+
+			if (target === "daily") {
+				const filePath = dailyPath(todayStr());
+				const existing = readFileSafe(filePath) ?? "";
+				const existingPreview = buildPreview(existing, {
+					maxLines: RESPONSE_PREVIEW_MAX_LINES,
+					maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+					mode: "end",
+				});
+				const existingSnippet = existingPreview.preview
+					? `\n\n${formatPreviewBlock("Existing daily log preview", existing, "end")}`
+					: "\n\nDaily log was empty.";
+
+				const separator = existing.trim() ? "\n\n" : "";
+				const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
+				fs.writeFileSync(filePath, existing + separator + stamped, "utf-8");
+				await ensureQmdAvailableForUpdate();
+				scheduleQmdUpdate();
+				return {
+					content: [{ type: "text", text: `Appended to daily log: ${filePath}${existingSnippet}` }],
+					details: {
+						path: filePath,
+						target,
+						mode: "append",
+						sessionId: sid,
+						timestamp: ts,
+						qmdUpdateMode: getQmdUpdateMode(),
+						existingPreview,
+					},
+				};
+			}
+
+			// long_term
+			const existing = readFileSafe(MEMORY_FILE) ?? "";
+			const existingPreview = buildPreview(existing, {
+				maxLines: RESPONSE_PREVIEW_MAX_LINES,
+				maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+				mode: "middle",
+			});
+			const existingSnippet = existingPreview.preview
+				? `\n\n${formatPreviewBlock("Existing MEMORY.md preview", existing, "middle")}`
+				: "\n\nMEMORY.md was empty.";
+
+			if (mode === "overwrite") {
+				const stamped = `<!-- last updated: ${ts} [${sid}] -->\n${content}`;
+				fs.writeFileSync(MEMORY_FILE, stamped, "utf-8");
+				await ensureQmdAvailableForUpdate();
+				scheduleQmdUpdate();
+				return {
+					content: [{ type: "text", text: `Overwrote MEMORY.md${existingSnippet}` }],
+					details: {
+						path: MEMORY_FILE,
+						target,
+						mode: "overwrite",
+						sessionId: sid,
+						timestamp: ts,
+						qmdUpdateMode: getQmdUpdateMode(),
+						existingPreview,
+					},
+				};
+			}
+
+			// append (default)
+			const separator = existing.trim() ? "\n\n" : "";
+			const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
+			fs.writeFileSync(MEMORY_FILE, existing + separator + stamped, "utf-8");
+			await ensureQmdAvailableForUpdate();
+			scheduleQmdUpdate();
+			return {
+				content: [{ type: "text", text: `Appended to MEMORY.md${existingSnippet}` }],
+				details: {
+					path: MEMORY_FILE,
+					target,
+					mode: "append",
+					sessionId: sid,
+					timestamp: ts,
+					qmdUpdateMode: getQmdUpdateMode(),
+					existingPreview,
+				},
+			};
+		},
+	});
+
+	// --- scratchpad tool ---
+	pi.registerTool({
+		name: "scratchpad",
+		label: "Scratchpad",
+		description: [
+			"Manage a checklist of things to fix later or keep in mind. Actions:",
+			"- 'add': Add a new unchecked item (- [ ] text)",
+			"- 'done': Mark an item as done (- [x] text). Match by substring.",
+			"- 'undo': Uncheck a done item back to open. Match by substring.",
+			"- 'clear_done': Remove all checked items from the list.",
+			"- 'list': Show all items.",
+		].join("\n"),
+		parameters: Type.Object({
+			action: StringEnum(["add", "done", "undo", "clear_done", "list"] as const, {
+				description: "What to do",
+			}),
+			text: Type.Optional(
+				Type.String({ description: "Item text for add, or substring to match for done/undo" }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			ensureDirs();
+			const { action, text } = params;
+			const sid = shortSessionId(ctx.sessionManager.getSessionId());
+			const ts = nowTimestamp();
+
+			const existing = readFileSafe(SCRATCHPAD_FILE) ?? "";
+			let items = parseScratchpad(existing);
+
+			if (action === "list") {
+				if (items.length === 0) {
+					return { content: [{ type: "text", text: "Scratchpad is empty." }], details: {} };
+				}
+				const serialized = serializeScratchpad(items);
+				const preview = buildPreview(serialized, {
+					maxLines: RESPONSE_PREVIEW_MAX_LINES,
+					maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+					mode: "start",
+				});
+				return {
+					content: [{ type: "text", text: formatPreviewBlock("Scratchpad preview", serialized, "start") }],
+					details: {
+						count: items.length,
+						open: items.filter((i) => !i.done).length,
+						preview,
+					},
+				};
+			}
+
+			if (action === "add") {
+				if (!text) {
+					return { content: [{ type: "text", text: "Error: 'text' is required for add." }], details: {} };
+				}
+				items.push({ done: false, text, meta: `<!-- ${ts} [${sid}] -->` });
+				const serialized = serializeScratchpad(items);
+				const preview = buildPreview(serialized, {
+					maxLines: RESPONSE_PREVIEW_MAX_LINES,
+					maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+					mode: "start",
+				});
+				fs.writeFileSync(SCRATCHPAD_FILE, serialized, "utf-8");
+				await ensureQmdAvailableForUpdate();
+				scheduleQmdUpdate();
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Added: - [ ] ${text}\n\n${formatPreviewBlock("Scratchpad preview", serialized, "start")}`,
+						},
+					],
+					details: { action, sessionId: sid, timestamp: ts, qmdUpdateMode: getQmdUpdateMode(), preview },
+				};
+			}
+
+			if (action === "done" || action === "undo") {
+				if (!text) {
+					return { content: [{ type: "text", text: `Error: 'text' is required for ${action}.` }], details: {} };
+				}
+				const needle = text.toLowerCase();
+				const targetDone = action === "done";
+				let matched = false;
+				for (const item of items) {
+					if (item.done !== targetDone && item.text.toLowerCase().includes(needle)) {
+						item.done = targetDone;
+						matched = true;
+						break;
+					}
+				}
+				if (!matched) {
+					return {
+						content: [{ type: "text", text: `No matching ${targetDone ? "open" : "done"} item found for: "${text}"` }],
+						details: {},
+					};
+				}
+				const serialized = serializeScratchpad(items);
+				const preview = buildPreview(serialized, {
+					maxLines: RESPONSE_PREVIEW_MAX_LINES,
+					maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+					mode: "start",
+				});
+				fs.writeFileSync(SCRATCHPAD_FILE, serialized, "utf-8");
+				await ensureQmdAvailableForUpdate();
+				scheduleQmdUpdate();
+				return {
+					content: [{ type: "text", text: `Updated.\n\n${formatPreviewBlock("Scratchpad preview", serialized, "start")}` }],
+					details: { action, sessionId: sid, timestamp: ts, qmdUpdateMode: getQmdUpdateMode(), preview },
+				};
+			}
+
+			if (action === "clear_done") {
+				const before = items.length;
+				items = items.filter((i) => !i.done);
+				const removed = before - items.length;
+				const serialized = serializeScratchpad(items);
+				const preview = buildPreview(serialized, {
+					maxLines: RESPONSE_PREVIEW_MAX_LINES,
+					maxChars: RESPONSE_PREVIEW_MAX_CHARS,
+					mode: "start",
+				});
+				fs.writeFileSync(SCRATCHPAD_FILE, serialized, "utf-8");
+				await ensureQmdAvailableForUpdate();
+				scheduleQmdUpdate();
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Cleared ${removed} done item(s).\n\n${formatPreviewBlock("Scratchpad preview", serialized, "start")}`,
+						},
+					],
+					details: { action, removed, qmdUpdateMode: getQmdUpdateMode(), preview },
+				};
+			}
+
+			return { content: [{ type: "text", text: `Unknown action: ${action}` }], details: {} };
+		},
+	});
+
+	// --- memory_read tool ---
+	pi.registerTool({
+		name: "memory_read",
+		label: "Memory Read",
+		description: [
+			"Read a memory file. Targets:",
+			"- 'long_term': Read MEMORY.md",
+			"- 'scratchpad': Read SCRATCHPAD.md",
+			"- 'daily': Read a specific day's log (default: today). Pass date as YYYY-MM-DD.",
+			"- 'list': List all daily log files.",
+		].join("\n"),
+		parameters: Type.Object({
+			target: StringEnum(["long_term", "scratchpad", "daily", "list"] as const, {
+				description: "What to read",
+			}),
+			date: Type.Optional(
+				Type.String({ description: "Date for daily log (YYYY-MM-DD). Default: today." }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			ensureDirs();
+			const { target, date } = params;
+
+			if (target === "list") {
+				try {
+					const files = fs.readdirSync(DAILY_DIR).filter((f) => f.endsWith(".md")).sort().reverse();
+					if (files.length === 0) {
+						return { content: [{ type: "text", text: "No daily logs found." }], details: {} };
+					}
+					return {
+						content: [{ type: "text", text: `Daily logs:\n${files.map((f) => `- ${f}`).join("\n")}` }],
+						details: { files },
+					};
+				} catch {
+					return { content: [{ type: "text", text: "No daily logs directory." }], details: {} };
+				}
+			}
+
+			if (target === "daily") {
+				const d = date ?? todayStr();
+				const filePath = dailyPath(d);
+				const content = readFileSafe(filePath);
+				if (!content) {
+					return { content: [{ type: "text", text: `No daily log for ${d}.` }], details: {} };
+				}
+				return {
+					content: [{ type: "text", text: content }],
+					details: { path: filePath, date: d },
+				};
+			}
+
+			if (target === "scratchpad") {
+				const content = readFileSafe(SCRATCHPAD_FILE);
+				if (!content?.trim()) {
+					return { content: [{ type: "text", text: "SCRATCHPAD.md is empty or does not exist." }], details: {} };
+				}
+				return {
+					content: [{ type: "text", text: content }],
+					details: { path: SCRATCHPAD_FILE },
+				};
+			}
+
+			// long_term
+			const content = readFileSafe(MEMORY_FILE);
+			if (!content) {
+				return { content: [{ type: "text", text: "MEMORY.md is empty or does not exist." }], details: {} };
+			}
+			return {
+				content: [{ type: "text", text: content }],
+				details: { path: MEMORY_FILE },
+			};
+		},
+	});
+
+	// --- memory_search tool ---
+	pi.registerTool({
+		name: "memory_search",
+		label: "Memory Search",
+		description:
+			"Search across all memory files (MEMORY.md, SCRATCHPAD.md, daily logs).\n" +
+			"Modes:\n" +
+			"- 'keyword' (default, ~30ms): Fast BM25 search. Best for specific terms, dates, names, #tags, [[links]].\n" +
+			"- 'semantic' (~2s): Meaning-based search. Finds related concepts even with different wording.\n" +
+			"- 'deep' (~10s): Hybrid search with reranking. Use when other modes don't find what you need.\n" +
+			"If the first search doesn't find what you need, try rephrasing or switching modes. " +
+			"Keyword mode is best for specific terms; semantic mode finds related concepts even with different wording.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Search query" }),
+			mode: Type.Optional(
+				StringEnum(["keyword", "semantic", "deep"] as const, {
+					description: "Search mode. Default: 'keyword'.",
+				}),
+			),
+			limit: Type.Optional(Type.Number({ description: "Max results (default: 5)" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!qmdAvailable) {
+				// Re-check on demand in case qmd was installed after session start.
+				qmdAvailable = await detectQmd();
+			}
+
+			if (!qmdAvailable) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: qmdInstallInstructions(),
+						},
+					],
+					isError: true,
+					details: {},
+				};
+			}
+
+			let hasCollection = await checkCollection("pi-memory");
+			if (!hasCollection) {
+				const created = await setupQmdCollection();
+				if (created) {
+					hasCollection = true;
+				}
+			}
+			if (!hasCollection) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "Could not set up qmd pi-memory collection. Check that qmd is working and the memory directory exists.",
+						},
+					],
+					isError: true,
+					details: {},
+				};
+			}
+
+			const mode = params.mode ?? "keyword";
+			const limit = params.limit ?? 5;
+
+			try {
+				const results = await runQmdSearch(mode, params.query, limit);
+
+				if (results.length === 0) {
+					return {
+						content: [{ type: "text", text: `No results found for "${params.query}" (mode: ${mode}).` }],
+						details: { mode, query: params.query, count: 0 },
+					};
+				}
+
+				const formatted = results
+					.map((r, i) => {
+						const parts: string[] = [`### Result ${i + 1}`];
+						if (r.path) parts.push(`**File:** ${r.path}`);
+						if (r.score != null) parts.push(`**Score:** ${r.score}`);
+						const text = r.content ?? r.chunk ?? "";
+						if (text) parts.push(`\n${text}`);
+						return parts.join("\n");
+					})
+					.join("\n\n---\n\n");
+
+				return {
+					content: [{ type: "text", text: formatted }],
+					details: { mode, query: params.query, count: results.length },
+				};
+			} catch (err) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `memory_search error: ${err instanceof Error ? err.message : String(err)}`,
+						},
+					],
+					isError: true,
+					details: {},
+				};
+			}
+		},
+	});
+}