@oh-my-pi/pi-coding-agent 14.6.2 → 14.6.4

package/src/modes/controllers/command-controller.ts

@@ -17,7 +17,16 @@ import { clearClaudePluginRootsCache } from "../../discovery/helpers";
 import { getGatewayStatus } from "../../eval/py/gateway-coordinator";
 import { loadCustomShare } from "../../export/custom-share";
 import type { CompactOptions } from "../../extensibility/extensions/types";
-import { buildMemoryToolDeveloperInstructions, clearMemoryData, enqueueMemoryConsolidation } from "../../memories";
+import {
+	diffMentalModelContent,
+	type HindsightApi,
+	type HindsightSessionState,
+	loadHindsightConfig,
+	reloadMentalModelsForSession,
+	resolveSeedsForScope,
+	summarizeMentalModel,
+} from "../../hindsight";
+import { resolveMemoryBackend } from "../../memory-backend";
 import { BashExecutionComponent } from "../../modes/components/bash-execution";
 import { BorderedLoader } from "../../modes/components/bordered-loader";
 import { DynamicBorder } from "../../modes/components/dynamic-border";
@@ -570,11 +579,12 @@ export class CommandController {
 		const argumentText = text.slice(7).trim();
 		const action = argumentText.split(/\s+/, 1)[0]?.toLowerCase() || "view";
 		const agentDir = this.ctx.settings.getAgentDir();
+		const backend = resolveMemoryBackend(this.ctx.settings);
 
 		if (action === "view") {
-			const payload = await buildMemoryToolDeveloperInstructions(agentDir, this.ctx.settings);
+			const payload = await backend.buildDeveloperInstructions(agentDir, this.ctx.settings, this.ctx.session);
 			if (!payload) {
-				this.ctx.showWarning("Memory payload is empty (memories disabled or no memory summary found).");
+				this.ctx.showWarning("Memory payload is empty (memory backend off, disabled, or no memory available).");
 				return;
 			}
 			this.ctx.chatContainer.addChild(new Spacer(1));
@@ -589,7 +599,7 @@ export class CommandController {
 
 		if (action === "reset" || action === "clear") {
 			try {
-				await clearMemoryData(agentDir, this.ctx.sessionManager.getCwd());
+				await backend.clear(agentDir, this.ctx.sessionManager.getCwd(), this.ctx.session);
 				await this.ctx.session.refreshBaseSystemPrompt();
 				this.ctx.showStatus("Memory data cleared and system prompt refreshed.");
 			} catch (error) {
@@ -600,7 +610,7 @@ export class CommandController {
 
 		if (action === "enqueue" || action === "rebuild") {
 			try {
-				enqueueMemoryConsolidation(agentDir, this.ctx.sessionManager.getCwd());
+				await backend.enqueue(agentDir, this.ctx.sessionManager.getCwd(), this.ctx.session);
 				this.ctx.showStatus("Memory consolidation enqueued.");
 			} catch (error) {
 				this.ctx.showError(`Memory enqueue failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -608,7 +618,257 @@ export class CommandController {
 			return;
 		}
 
-		this.ctx.showError("Usage: /memory <view|clear|reset|enqueue|rebuild>");
+		if (action === "mm") {
+			await this.#handleMentalModelsSubcommand(argumentText);
+			return;
+		}
+
+		this.ctx.showError("Usage: /memory <view|clear|reset|enqueue|rebuild|mm ...>");
+	}
+
+	async #handleMentalModelsSubcommand(argumentText: string): Promise<void> {
+		// Parse: "mm <verb> [arg]"
+		const parts = argumentText.split(/\s+/).slice(1);
+		const verb = parts[0]?.toLowerCase() ?? "list";
+		const arg = parts[1];
+
+		const state = this.ctx.session.getHindsightSessionState();
+		const primary = state && !state.aliasOf ? state : undefined;
+		if (!primary) {
+			this.ctx.showError("Hindsight backend is not active for this session.");
+			return;
+		}
+		if (!primary.config.mentalModelsEnabled) {
+			this.ctx.showError("Mental models are disabled (hindsight.mentalModelsEnabled = false).");
+			return;
+		}
+
+		switch (verb) {
+			case "list":
+				await this.#mmList(primary);
+				return;
+			case "show":
+				if (!arg) return this.ctx.showError("Usage: /memory mm show <id>");
+				await this.#mmShow(primary, arg);
+				return;
+			case "refresh":
+				await this.#mmRefresh(primary, arg);
+				return;
+			case "history":
+				if (!arg) return this.ctx.showError("Usage: /memory mm history <id>");
+				await this.#mmHistory(primary, arg);
+				return;
+			case "seed":
+				await this.#mmSeed(primary);
+				return;
+			case "reload":
+				await this.#mmReload(primary);
+				return;
+			case "delete":
+			case "remove":
+				if (!arg) return this.ctx.showError("Usage: /memory mm delete <id>");
+				await this.#mmDelete(primary, arg);
+				return;
+			default:
+				this.ctx.showError("Usage: /memory mm <list|show|refresh|history|seed|reload|delete>");
+		}
+	}
+
+	async #mmList(state: HindsightSessionState): Promise<void> {
+		const client: HindsightApi = state.client;
+		try {
+			const response = await client.listMentalModels(state.bankId, { detail: "metadata" });
+			const items = response.items ?? [];
+			if (items.length === 0) {
+				this.ctx.showStatus(`No mental models on bank ${state.bankId}.`);
+				return;
+			}
+			const lines = items
+				.slice()
+				.sort((a, b) => a.id.localeCompare(b.id))
+				.map(summarizeMentalModel);
+			showMarkdownPanel(this.ctx, `Mental Models — ${state.bankId}`, lines.join("\n"));
+		} catch (error) {
+			this.ctx.showError(`mm list failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	async #mmShow(state: HindsightSessionState, id: string): Promise<void> {
+		try {
+			const model = await state.client.getMentalModel(state.bankId, id, { detail: "content" });
+			if (!model) {
+				this.ctx.showError(`Mental model not found: ${id}`);
+				return;
+			}
+			const tags = model.tags && model.tags.length > 0 ? `\n_tags: ${model.tags.join(", ")}_` : "";
+			const refreshed = model.last_refreshed_at ? `\n_last refreshed: ${model.last_refreshed_at}_` : "";
+			const sourceQuery = model.source_query ? `\n\n**Source query:** ${model.source_query}` : "";
+			const content = (model.content ?? "_(empty — background reflect may still be running)_").trim();
+			showMarkdownPanel(
+				this.ctx,
+				model.name,
+				`**id:** \`${model.id}\`${tags}${refreshed}${sourceQuery}\n\n${content}`,
+			);
+		} catch (error) {
+			this.ctx.showError(`mm show failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	async #mmRefresh(state: HindsightSessionState, id: string | undefined): Promise<void> {
+		try {
+			if (id) {
+				// Single-model refresh is explicit operator intent: bypass the
+				// auto-refresh filter so curated/manual models can still be
+				// refreshed on demand.
+				await state.client.refreshMentalModel(state.bankId, id);
+				this.ctx.showStatus(`Refresh queued for mental model ${id}.`);
+			} else {
+				// Bulk refresh: only touch models that opted into automatic
+				// refresh via `trigger.refresh_after_consolidation`. Curated
+				// models are reviewed before publishing and must not be
+				// silently regenerated by a bank-wide refresh sweep. Reading
+				// `detail: "content"` here is required because the trigger
+				// field is excluded from `detail: "metadata"`.
+				const list = await state.client.listMentalModels(state.bankId, { detail: "content" });
+				const items = list.items ?? [];
+				if (items.length === 0) {
+					this.ctx.showStatus(`No mental models on bank ${state.bankId}.`);
+					return;
+				}
+				const targets = items.filter(m => m.trigger?.refresh_after_consolidation === true);
+				const skipped = items.length - targets.length;
+				if (targets.length === 0) {
+					this.ctx.showStatus(
+						`No mental models opted into auto-refresh; ${skipped} curated model(s) left untouched. Pass an explicit id to refresh one of them.`,
+					);
+					return;
+				}
+				let queued = 0;
+				for (const item of targets) {
+					try {
+						await state.client.refreshMentalModel(state.bankId, item.id);
+						queued++;
+					} catch (error) {
+						this.ctx.showWarning(
+							`Refresh failed for ${item.id}: ${error instanceof Error ? error.message : String(error)}`,
+						);
+					}
+				}
+				const skippedSuffix = skipped > 0 ? `; skipped ${skipped} curated model(s)` : "";
+				this.ctx.showStatus(
+					`Refresh queued for ${queued}/${targets.length} auto-refresh model(s)${skippedSuffix}.`,
+				);
+			}
+			// Reload the cache after a brief grace so the new content (if the refresh
+			// completes synchronously on the server) flows into the system prompt.
+			await Bun.sleep(500);
+			await reloadMentalModelsForSession(state.session);
+		} catch (error) {
+			this.ctx.showError(`mm refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	async #mmHistory(state: HindsightSessionState, id: string): Promise<void> {
+		try {
+			const [model, history] = await Promise.all([
+				state.client.getMentalModel(state.bankId, id, { detail: "content" }),
+				state.client.getMentalModelHistory(state.bankId, id),
+			]);
+			if (!model) {
+				this.ctx.showError(`Mental model not found: ${id}`);
+				return;
+			}
+			if (history.length === 0) {
+				this.ctx.showStatus(`No history recorded for ${id}.`);
+				return;
+			}
+			// History is most-recent first. Each entry stores the content BEFORE that
+			// change. To diff "what changed at entry N", compare entry N's
+			// previous_content (= state before that change) with entry N-1's
+			// previous_content (= state after that change, which was state before
+			// the next change). For the most recent change, compare against the
+			// model's CURRENT content.
+			const sections: string[] = [];
+			for (let i = 0; i < history.length; i++) {
+				const before = history[i].previous_content ?? "";
+				const after = i === 0 ? (model.content ?? "") : (history[i - 1].previous_content ?? "");
+				const diff = diffMentalModelContent(before, after);
+				sections.push(`### ${history[i].changed_at}\n\n\`\`\`diff\n${diff}\n\`\`\``);
+			}
+			showMarkdownPanel(this.ctx, `History — ${model.name}`, sections.join("\n\n"));
+		} catch (error) {
+			this.ctx.showError(`mm history failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	async #mmSeed(state: HindsightSessionState): Promise<void> {
+		try {
+			const config = loadHindsightConfig(this.ctx.settings);
+			const seeds = resolveSeedsForScope(
+				{
+					bankId: state.bankId,
+					retainTags: state.retainTags,
+					recallTags: state.recallTags,
+					recallTagsMatch: state.recallTagsMatch,
+				},
+				config.scoping,
+			);
+			if (seeds.length === 0) {
+				this.ctx.showStatus(`No built-in seeds apply to scoping=${config.scoping}.`);
+				return;
+			}
+			const list = await state.client.listMentalModels(state.bankId, { detail: "metadata" });
+			const existing = new Set((list.items ?? []).map(m => m.id));
+			let created = 0;
+			let skipped = 0;
+			for (const seed of seeds) {
+				if (existing.has(seed.id)) {
+					skipped++;
+					continue;
+				}
+				try {
+					await state.client.createMentalModel(state.bankId, seed.name, seed.sourceQuery, {
+						id: seed.id,
+						tags: seed.tags.length > 0 ? seed.tags : undefined,
+						maxTokens: seed.maxTokens,
+						trigger: seed.trigger,
+					});
+					created++;
+				} catch (error) {
+					this.ctx.showWarning(
+						`Seed failed for ${seed.id}: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+			this.ctx.showStatus(`Seeded ${created} new mental model(s); ${skipped} already present.`);
+		} catch (error) {
+			this.ctx.showError(`mm seed failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	async #mmReload(state: HindsightSessionState): Promise<void> {
+		const ok = await reloadMentalModelsForSession(state.session);
+		if (ok) {
+			this.ctx.showStatus("Mental-model cache reloaded.");
+		} else {
+			this.ctx.showError("Reload failed (Hindsight backend not active or mental models disabled).");
+		}
+	}
+
+	async #mmDelete(state: HindsightSessionState, id: string): Promise<void> {
+		try {
+			const removed = await state.client.deleteMentalModel(state.bankId, id);
+			if (!removed) {
+				this.ctx.showError(`Mental model not found: ${id}`);
+				return;
+			}
+			// Drop the cached snippet so the closing tag does not silently keep
+			// stale content in the system prompt until the next agent_end TTL.
+			await reloadMentalModelsForSession(state.session);
+			this.ctx.showStatus(`Deleted mental model ${id} from bank ${state.bankId}.`);
+		} catch (error) {
+			this.ctx.showError(`mm delete failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 
 	async #runNewSessionFlow(options?: NewSessionOptions, label: string = "New session started"): Promise<void> {

package/src/modes/controllers/event-controller.ts

@@ -53,6 +53,7 @@ export class EventController {
 			todo_reminder: e => this.#handleTodoReminder(e),
 			todo_auto_clear: e => this.#handleTodoAutoClear(e),
 			irc_message: e => this.#handleIrcMessage(e),
+			notice: e => this.#handleNotice(e),
 		} satisfies AgentSessionEventHandlers;
 	}
 
@@ -223,6 +224,17 @@ export class EventController {
 		this.ctx.ui.requestRender();
 	}
 
+	async #handleNotice(event: Extract<AgentSessionEvent, { type: "notice" }>): Promise<void> {
+		const message = event.source ? `${event.source}: ${event.message}` : event.message;
+		if (event.level === "error") {
+			this.ctx.showError(message);
+		} else if (event.level === "warning") {
+			this.ctx.showWarning(message);
+		} else {
+			this.ctx.showStatus(message);
+		}
+	}
+
 	async #handleMessageUpdate(event: Extract<AgentSessionEvent, { type: "message_update" }>): Promise<void> {
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;

package/src/modes/controllers/selector-controller.ts

@@ -1,18 +1,15 @@
-import * as os from "node:os";
-import * as path from "node:path";
 import { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { getOAuthProviders } from "@oh-my-pi/pi-ai/utils/oauth";
 import type { OAuthProvider } from "@oh-my-pi/pi-ai/utils/oauth/types";
 import type { Component, OverlayHandle } from "@oh-my-pi/pi-tui";
 import { Input, Loader, Spacer, Text } from "@oh-my-pi/pi-tui";
-import { getAgentDbPath, getConfigDirName, getProjectDir } from "@oh-my-pi/pi-utils";
-import { invalidate as invalidateFsCache } from "../../capability/fs";
+import { getAgentDbPath, getProjectDir } from "@oh-my-pi/pi-utils";
 import { getRoleInfo } from "../../config/model-registry";
 import { formatModelSelectorValue } from "../../config/model-resolver";
 import { settings } from "../../config/settings";
 import { DebugSelectorComponent } from "../../debug";
 import { disableProvider, enableProvider } from "../../discovery";
-import { clearClaudePluginRootsCache, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
+import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
 import {
 	getInstalledPluginsRegistryPath,
 	getMarketplacesCacheDir,
@@ -451,13 +448,7 @@ export class SelectorController {
 			projectInstalledRegistryPath: (await resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
 			marketplacesCacheDir: getMarketplacesCacheDir(),
 			pluginsCacheDir: getPluginsCacheDir(),
-			clearPluginRootsCache: (extraPaths?: readonly string[]) => {
-				const home = os.homedir();
-				invalidateFsCache(path.join(home, ".claude", "plugins", "installed_plugins.json"));
-				invalidateFsCache(path.join(home, getConfigDirName(), "plugins", "installed_plugins.json"));
-				for (const p of extraPaths ?? []) invalidateFsCache(p);
-				clearClaudePluginRootsCache();
-			},
+			clearPluginRootsCache: clearPluginRootsAndCaches,
 		});
 
 		const [marketplaces, installed] = await Promise.all([mgr.listMarketplaces(), mgr.listInstalledPlugins()]);

package/src/modes/theme/theme.ts

@@ -186,6 +186,7 @@ export type SymbolKey =
 	| "tab.context"
 	| "tab.editing"
 	| "tab.tools"
+	| "tab.memory"
 	| "tab.tasks"
 	| "tab.providers";
 
@@ -346,6 +347,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"tab.context": "📋",
 	"tab.editing": "💻",
 	"tab.tools": "🔧",
+	"tab.memory": "🧠",
 	"tab.tasks": "📦",
 	"tab.providers": "🌐",
 };
@@ -599,6 +601,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"tab.context": "󰘸",
 	"tab.editing": "",
 	"tab.tools": "󰠭",
+	"tab.memory": "󰧑",
 	"tab.tasks": "󰐱",
 	"tab.providers": "󰖟",
 };
@@ -757,6 +760,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"tab.context": "[X]",
 	"tab.editing": "[E]",
 	"tab.tools": "[T]",
+	"tab.memory": "[Y]",
 	"tab.tasks": "[K]",
 	"tab.providers": "[P]",
 };

package/src/prompts/tools/github.md

@@ -10,6 +10,9 @@ Pick the operation via `op`. Each op uses a subset of the parameters:
 - `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout` (carries push metadata). Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
 - `search_issues` — Search issues using normal GitHub issue search syntax. Required `query`. Optional `repo`, `limit`.
 - `search_prs` — Search pull requests using normal GitHub PR search syntax. Required `query`. Optional `repo`, `limit`.
+- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments.
+- `search_commits` — Search commits across GitHub. Required `query`. Optional `repo`, `limit`. Returns short SHA, author, and the first line of each commit message.
+- `search_repos` — Search repositories across GitHub. Required `query`. Optional `limit` (use query qualifiers like `org:`, `language:` instead of `repo`).
 - `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Streams snapshots, fast-fails on the first detected job failure (with a brief grace period to capture concurrent failures), then fetches tailed logs for the failed jobs. The full failed-job logs are saved as a session artifact for on-demand reads.
 </instruction>
 

package/src/prompts/tools/hashline.md

@@ -8,15 +8,15 @@ This format is purely textual. The tool has NO awareness of language, indentatio
 
 <ops>
 @PATH            header: subsequent ops apply to PATH
-< ANCHOR         insert lines BEFORE the anchored line (or BOF); payload follows as `|TEXT` lines
-+ ANCHOR         insert lines AFTER  the anchored line (or EOF); payload follows as `|TEXT` lines
+< ANCHOR         insert lines BEFORE the anchored line (or BOF); payload follows as `{{hsep}}TEXT` lines
++ ANCHOR         insert lines AFTER  the anchored line (or EOF); payload follows as `{{hsep}}TEXT` lines
 - A..B           delete the line range (inclusive); `- A` for one line
-= A..B           replace the range with payload `|TEXT` lines, or with one blank line if no payload follows
+= A..B           replace the range with payload `{{hsep}}TEXT` lines, or with one blank line if no payload follows
 </ops>
 
 <rules>
-- Every line of inserted/replacement content **MUST** be emitted as a payload line starting with `|`.
-- `|` is syntax, not content. The inserted text begins after the first `|`; use a bare `|` to insert a blank line.
+- Every line of inserted/replacement content **MUST** be emitted as a payload line starting with `{{hsep}}`.
+- `{{hsep}}` is syntax, not content. The inserted text begins after the first `{{hsep}}`; use a bare `{{hsep}}` to insert a blank line.
 - `< A` inserts before line A; `+ A` inserts after line A. `< BOF` / `+ BOF` both prepend; `< EOF` / `+ EOF` both append.
 - `= A..B` replaces the inclusive range with the following payload lines. `= A` (or `= A..B`) with no payload blanks the range to a single empty line.
 - `- A..B` deletes the inclusive range; omit `..B` for one line.
@@ -35,30 +35,34 @@ This format is purely textual. The tool has NO awareness of language, indentatio
 # Replace one line (preserve the leading tab from the original)
 @a.ts
 = {{hrefr 5}}
-|	return clean.trim().toUpperCase();
+{{hsep}}	return clean.trim().toUpperCase();
 
 # Replace a contiguous range with multiple lines
 @a.ts
 = {{hrefr 3}}..{{hrefr 6}}
-|export function label(name: string): string {
-|	const clean = (name || DEF).trim();
-|	return clean.length === 0 ? DEF : clean.toUpperCase();
-|}
+{{hsep}}export function label(name: string): string {
+{{hsep}}	const clean = (name || DEF).trim();
+{{hsep}}	return clean.length === 0 ? DEF : clean.toUpperCase();
+{{hsep}}}
 
 # Insert BEFORE a line
 @a.ts
 < {{hrefr 5}}
-|	const debug = false;
+{{hsep}}	const debug = false;
 
 # Insert AFTER a line
 @a.ts
 + {{hrefr 4}}
-|	if (clean.length === 0) return DEF;
+{{hsep}}	if (clean.length === 0) return DEF;
+
+# Append WITHIN a line
+@a.ts
++ {{hrefr 4}}{{hsep}} // first run
 
 # Append to end of file
 @a.ts
 + EOF
-|export const done = true;
+{{hsep}}export const done = true;
 
 # Delete a single line
 @a.ts
@@ -70,9 +74,10 @@ This format is purely textual. The tool has NO awareness of language, indentatio
 </examples>
 
 <critical>
-- Always copy anchors exactly from tool output, but **NEVER** include line content after the `|` separator in the op line.
+- Always copy anchors exactly from tool output, but **NEVER** include line content after the `{{hsep}}` separator in the op line.
 - Only emit changed lines. Do not restate unchanged context as payload.
-- Every inserted/replacement content line **MUST** start with `|`; raw content lines are invalid.
+- Every inserted/replacement content line **MUST** start with `{{hsep}}`; raw content lines are invalid.
 - Do not write unified diff syntax (`@@`, `-OLD`, `+NEW`).
-- To replace a block, use one `= A..B` op followed by all replacement `|TEXT` payload lines.
+- To replace a block, use one `= A..B` op followed by all replacement `{{hsep}}TEXT` payload lines.
+- `= A..B` deletes the range; payload is what's written. If a payload edge line already exists immediately outside `A..B`, widen the range to cover it — otherwise it duplicates.
 </critical>

package/src/prompts/tools/read.md

@@ -14,7 +14,7 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 
 |`sel` value|Behavior|
 |---|---|
-|*(omitted)*|Read full file (up to {{DEFAULT_LIMIT}} lines)|
+|_(omitted)_|Read full file (up to {{DEFAULT_LIMIT}} lines)|
 |`50`|Read from line 50 onward|
 |`50-200`|Read lines 50-200|
 |`50+150`|Read 150 lines starting at line 50|
@@ -22,21 +22,24 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 
 # Filesystem
 - Reading a directory path returns a list of dirents.
-{{#if IS_HASHLINE_MODE}}
+  {{#if IS_HL_MODE}}
 - Reading a file returns lines prefixed with anchors (line+hash): `41th|def alpha():`
-{{else}}
-{{#if IS_LINE_NUMBER_MODE}}
+  {{else}}
+  {{#if IS_LINE_NUMBER_MODE}}
 - Reading a file returns lines prefixed with line numbers: `41|def alpha():`
-{{/if}}
-{{/if}}
+  {{/if}}
+  {{/if}}
 
 # Inspection
+
 Extracts text from PDF, Word, PowerPoint, Excel, RTF, EPUB, and Jupyter notebook files. Can inspect images.
 
 # Directories & Archives
+
 Directories and archive roots return a list of entries. Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read contents.
 
 # SQLite Databases
+
 For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db` — list tables with row counts
 - `file.db:table` — schema + sample rows
@@ -46,6 +49,7 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db?q=SELECT …` — read-only SELECT query
 
 # URLs
+
 Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout.
 </instruction>
 

package/src/prompts/tools/recall.md

@@ -0,0 +1,5 @@
+Search long-term memory for relevant information. Returns raw matching entries ranked by relevance.
+
+Use proactively — before answering questions about past conversations, user preferences, project decisions, or any topic where prior context would help accuracy. When in doubt, recall first.
+
+Prefer `recall` when you need specific facts or entries. Use `reflect` instead when you need a synthesised answer across many memories.

package/src/prompts/tools/reflect.md

@@ -0,0 +1,5 @@
+Generate a synthesised answer by reasoning over long-term memory. Unlike `recall` (which returns raw entries), `reflect` blends relevant memories into a single coherent response.
+
+Use for open-ended questions that span many stored facts: "What do you know about this user?", "Summarize project decisions.", "What are my preferences for X?"
+
+Provide an optional `context` to focus the synthesis on a specific angle or sub-topic.

package/src/prompts/tools/retain.md

@@ -0,0 +1,5 @@
+Store one or more facts in long-term memory for future sessions.
+
+Use for durable, reusable knowledge: user preferences, project decisions, architectural choices, and anything that would improve future responses if recalled. Ephemeral task state does not belong here.
+
+Each item must be specific and self-contained — include who, what, when, and why. Batch related facts in a single call; they are deduplicated and consolidated together.

package/src/prompts/tools/search.md

@@ -7,7 +7,7 @@ Searches files using powerful regex matching.
 </instruction>
 
 <output>
-{{#if IS_HASHLINE_MODE}}
+{{#if IS_HL_MODE}}
 - Text output is anchor-prefixed: `*5th|content` (match) or ` 9x}|content` (context, leading space). The 2-char suffix is a content fingerprint.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}

package/src/sdk.ts

@@ -61,6 +61,7 @@ import {
 } from "./extensibility/extensions";
 import { loadSkills as loadSkillsInternal, type Skill, type SkillWarning } from "./extensibility/skills";
 import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal } from "./extensibility/slash-commands";
+import type { HindsightSessionState } from "./hindsight/state";
 import {
 	AgentProtocolHandler,
 	ArtifactProtocolHandler,
@@ -82,7 +83,8 @@ import {
 	selectDiscoverableMCPToolNamesByServer,
 	summarizeDiscoverableMCPTools,
 } from "./mcp/discoverable-tool-metadata";
-import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
+import { getMemoryRoot } from "./memories";
+import { resolveMemoryBackend } from "./memory-backend";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import {
@@ -215,6 +217,8 @@ export interface CreateAgentSessionOptions {
 	requireYieldTool?: boolean;
 	/** Task recursion depth (for subagent sessions). Default: 0 */
 	taskDepth?: number;
+	/** Parent Hindsight state to alias for subagent memory tools. */
+	parentHindsightSessionState?: HindsightSessionState;
 	/** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */
 	agentId?: string;
 	/** Display name for the agent in IRC. Default: "main" or "sub". */
@@ -967,6 +971,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			trackEvalExecution: (execution, abortController) =>
 				session ? session.trackEvalExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			getHindsightSessionState: () => session?.getHindsightSessionState(),
 			getAgentId: () => resolvedAgentId,
 			getToolByName: name => session?.getToolByName(name),
 			agentRegistry,
@@ -1334,7 +1339,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const promptTools = buildSystemPromptToolMetadata(tools, {
 				search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
 			});
-			const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
+			const memoryInstructions = await resolveMemoryBackend(settings).buildDeveloperInstructions(
+				agentDir,
+				settings,
+				session,
+			);
 
 			// Build combined append prompt: memory instructions + MCP server instructions
 			const serverInstructions = mcpManager?.getServerInstructions();
@@ -1747,13 +1756,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 
 		logger.time("startMemoryStartupTask", () =>
-			startMemoryStartupTask({
-				session,
-				settings,
-				modelRegistry,
-				agentDir,
-				taskDepth,
-			}),
+			Promise.resolve(
+				resolveMemoryBackend(settings).start({
+					session,
+					settings,
+					modelRegistry,
+					agentDir,
+					taskDepth,
+					parentHindsightSessionState: options.parentHindsightSessionState,
+				}),
+			),
 		);
 
 		// Wire MCP manager callbacks to session for reactive tool updates.