@oh-my-pi/pi-coding-agent 15.5.15 → 15.7.0

package/src/tools/bash.ts

@@ -7,7 +7,7 @@ import type {
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { ImageProtocol, TERMINAL, Text } from "@oh-my-pi/pi-tui";
+import { ImageProtocol, TERMINAL } from "@oh-my-pi/pi-tui";
 import { getProjectDir, isEnoent, logger, prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { AsyncJobManager } from "../async";
@@ -15,6 +15,7 @@ import { type BashResult, executeBash } from "../exec/bash-executor";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { InternalUrlRouter } from "../internal-urls";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
+import { shimmerEnabled } from "../modes/theme/shimmer";
 import { highlightCode, type Theme } from "../modes/theme/theme";
 import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
 import type { ClientBridgeTerminalExitStatus, ClientBridgeTerminalOutput } from "../session/client-bridge";
@@ -129,6 +130,8 @@ export interface BashToolDetails {
 	timeoutSeconds?: number;
 	requestedTimeoutSeconds?: number;
 	wallTimeMs?: number;
+	/** Exit code of a command that ran to completion but failed (non-zero). */
+	exitCode?: number;
 	terminalId?: string;
 	async?: {
 		state: "running" | "completed" | "failed";
@@ -281,17 +284,19 @@ function formatWallTimeNotice(wallTimeMs: number): string {
 	return `Wall time: ${formatWallTimeSeconds(wallTimeMs)} seconds`;
 }
 
+function formatExitCodeNotice(exitCode: number): string {
+	return `Command exited with code ${exitCode}`;
+}
+
 /**
- * Strip the trailing `Wall time: <secs> seconds` notice from text so the TUI
- * can render the wall time via its styled `[Wall: …]` label without echoing
- * the same value verbatim in the output pane.
+ * Strip the trailing occurrence of `notice` (plus a single surrounding newline
+ * on each side) so the TUI can echo the value via a styled footer label
+ * instead of repeating it verbatim in the output pane. The notice is
+ * reconstructed from the same value the result was tagged with, so a literal
+ * sub-string match never strips a coincidental in-output token — only the
+ * exact line we appended in #buildCompletedResult.
  */
-function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): string {
-	if (wallTimeMs === undefined) return text;
-	// Reconstruct the notice from the same value the result was tagged with so
-	// a literal sub-string match never strips a coincidental in-output token —
-	// only the exact line we appended in #buildCompletedResult.
-	const notice = formatWallTimeNotice(wallTimeMs);
+function stripTrailingNotice(text: string, notice: string): string {
 	const idx = text.lastIndexOf(notice);
 	if (idx === -1) return text;
 	let start = idx;
@@ -301,6 +306,16 @@ function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): stri
 	return (text.slice(0, start) + text.slice(end)).trimEnd();
 }
 
+function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): string {
+	if (wallTimeMs === undefined) return text;
+	return stripTrailingNotice(text, formatWallTimeNotice(wallTimeMs));
+}
+
+function stripExitCodeNotice(text: string, exitCode: number | undefined): string {
+	if (exitCode === undefined) return text;
+	return stripTrailingNotice(text, formatExitCodeNotice(exitCode));
+}
+
 /**
  * Bash tool implementation.
  *
@@ -357,7 +372,15 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return outputText || "(no output)";
 	}
 
-	#buildResultText(result: BashResult | BashInteractiveResult, timeoutSec: number, outputText: string): string {
+	/**
+	 * Throw for outcomes that are *not* a completed command: user/timeout
+	 * aborts and a missing exit status. The foreground and bridge callers plus
+	 * the async job manager rely on these throwing so cancellations surface as
+	 * aborts and jobs are recorded as failed. A definite non-zero exit is a
+	 * completed command that failed; #buildCompletedResult surfaces it as an
+	 * error *result* (carrying execution details) rather than a throw.
+	 */
+	#throwIfUnfinished(result: BashResult | BashInteractiveResult, timeoutSec: number, outputText: string): void {
 		if (result.cancelled) {
 			throw new ToolError(normalizeResultOutput(result) || "Command aborted");
 		}
@@ -367,10 +390,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (result.exitCode === undefined) {
 			throw new ToolError(`${outputText}\n\nCommand failed: missing exit status`);
 		}
-		if (result.exitCode !== 0) {
-			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
-		}
-		return outputText;
 	}
 
 	#buildCompletedResult(
@@ -383,6 +402,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			wallTimeMs?: number;
 		} = {},
 	): AgentToolResult<BashToolDetails> {
+		const exitCode = result.exitCode;
+		const failedExit = exitCode !== undefined && exitCode !== 0;
+
 		const outputLines = [this.#formatResultOutput(result)];
 		const notices: string[] = [];
 		if (options.wallTimeMs !== undefined) {
@@ -394,7 +416,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 		}
 		if (notices.length > 0) outputLines.push("", ...notices);
+		if (failedExit) outputLines.push("", formatExitCodeNotice(exitCode));
 		const outputText = outputLines.join("\n");
+
+		// Aborts / timeouts / missing-status still propagate as thrown errors.
+		this.#throwIfUnfinished(result, timeoutSec, outputText);
+
 		const details: BashToolDetails = { timeoutSeconds: timeoutSec };
 		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
@@ -405,8 +432,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (options.wallTimeMs !== undefined) {
 			details.wallTimeMs = options.wallTimeMs;
 		}
+		if (failedExit) {
+			details.exitCode = exitCode;
+		}
 		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
-		this.#buildResultText(result, timeoutSec, outputText);
+		if (failedExit) resultBuilder.error();
 		return resultBuilder.done();
 	}
 
@@ -500,7 +530,16 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					});
 					const finalText = this.#extractTextResult(finalResult);
 					latestText = finalText;
+					// Hand the detailed result to the foreground auto-background
+					// waiter (which renders it, footer included) before deciding
+					// the job's terminal state.
 					completion.resolve({ kind: "completed", result: finalResult });
+					if (finalResult.isError === true) {
+						// A non-zero exit is a completed command that failed. Re-enter
+						// the failure path so the job manager records it as failed and
+						// delivers the error text, matching prior throw-based behavior.
+						throw new ToolError(finalText);
+					}
 					await reportProgress(finalText, { async: { state: "completed", jobId, type: "bash" } });
 					return finalText;
 				} catch (error) {
@@ -1007,15 +1046,6 @@ export function getBashEnvForDisplay(args: BashRenderArgs): Record<string, strin
 	return args.env ?? partialEnv;
 }
 
-export function formatBashCommand(args: BashRenderArgs): string {
-	const command = replaceTabs(args.command || "…");
-	const prompt = "$";
-	const cwd = getProjectDir();
-	const displayWorkdir = formatToolWorkingDirectory(args.cwd, cwd);
-	const renderedCommand = [formatBashEnvAssignments(getBashEnvForDisplay(args)), command].filter(Boolean).join(" ");
-	return displayWorkdir ? `${prompt} cd ${displayWorkdir} && ${renderedCommand}` : `${prompt} ${renderedCommand}`;
-}
-
 /**
  * Returns the bash command formatted for the result body: the dim `$ cd … &&`
  * prefix joined with syntax-highlighted command lines. The prefix is applied
@@ -1050,10 +1080,20 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 	return {
 		renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 			const renderArgs = toBashRenderArgs(args, config);
-			const cmdText = formatBashCommand(renderArgs);
 			const title = config.resolveTitle(args, options);
-			const text = renderStatusLine({ icon: "pending", title, description: cmdText }, uiTheme);
-			return new Text(text, 0, 0);
+			const cmdLines = formatBashCommandLines(renderArgs, uiTheme);
+			const header = renderStatusLine({ icon: "pending", title }, uiTheme);
+			const outputBlock = new CachedOutputBlock();
+			return {
+				render: (width: number): string[] =>
+					outputBlock.render(
+						{ header, state: "pending", sections: [{ lines: cmdLines }], width, animate: true },
+						uiTheme,
+					),
+				invalidate: () => {
+					outputBlock.invalidate();
+				},
+			};
 		},
 
 		renderResult(
@@ -1087,7 +1127,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					// double-print it alongside the styled warning line below.
 					const rawOutput = renderContext?.output ?? result.content?.find(c => c.type === "text")?.text ?? "";
 					const strippedOutput = stripOutputNotice(rawOutput, details?.meta);
-					const output = stripWallTimeNotice(strippedOutput, details?.wallTimeMs);
+					const withoutExit = stripExitCodeNotice(strippedOutput, details?.exitCode);
+					const output = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
 					const displayOutput = output.trimEnd();
 					const showingFullOutput = expanded && renderContext?.isFullOutput === true;
 
@@ -1106,6 +1147,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 								: `Timeout: ${timeoutSeconds}s`,
 						);
 					}
+					if (isError && typeof details?.exitCode === "number") {
+						statsParts.push(`Exit: ${details.exitCode}`);
+					}
 					const timeoutLine =
 						statsParts.length > 0
 							? uiTheme.fg(
@@ -1162,6 +1206,7 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 								{ label: uiTheme.fg("toolTitle", "Output"), lines: outputLines },
 							],
 							width,
+							animate: options.isPartial && shimmerEnabled(),
 						},
 						uiTheme,
 					);

package/src/tools/browser/tab-worker.ts

@@ -917,7 +917,7 @@ export class WorkerCore {
 						dispatchEvent: (event: unknown) => boolean;
 					}
 					const select = el as unknown as SelectLike;
-					if (!select || select.tagName !== "SELECT") throw new Error("tab.select() requires a <select> element");
+					if (select?.tagName !== "SELECT") throw new Error("tab.select() requires a <select> element");
 					const EventCtor = (
 						globalThis as unknown as { Event: new (type: string, init?: { bubbles: boolean }) => unknown }
 					).Event;

package/src/tools/eval.ts

@@ -10,10 +10,11 @@ import { defaultEvalSessionId } from "../eval/session-id";
 import type { EvalCellResult, EvalDisplayOutput, EvalLanguage, EvalStatusEvent, EvalToolDetails } from "../eval/types";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
+import { shimmerEnabled } from "../modes/theme/shimmer";
 import { getMarkdownTheme, type Theme } from "../modes/theme/theme";
 import evalDescription from "../prompts/tools/eval.md" with { type: "text" };
 import { DEFAULT_MAX_BYTES, OutputSink, type OutputSummary, TailBuffer } from "../session/streaming-output";
-import { renderCodeCell } from "../tui";
+import { borderShimmerTick, renderCodeCell } from "../tui";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { resolveEvalBackends, type ToolSession } from ".";
 import { truncateForPrompt } from "./approval";
@@ -857,7 +858,7 @@ function formatCellOutputLines(
 }
 
 export const evalToolRenderer = {
-	renderCall(args: EvalRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+	renderCall(args: EvalRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 		const cells = getRenderCells(args);
 
 		if (cells.length === 0) {
@@ -870,7 +871,8 @@ export const evalToolRenderer = {
 
 		return {
 			render: (width: number): string[] => {
-				const key = cells.map(c => `${c.language}:${c.title ?? ""}:${c.code.length}`).join("|");
+				const animate = options.isPartial && shimmerEnabled();
+				const key = `${animate ? borderShimmerTick() : 0}|${cells.map(c => `${c.language}:${c.title ?? ""}:${c.code.length}`).join("|")}`;
 				if (cached && cached.key === key && cached.width === width) {
 					return cached.result;
 				}
@@ -889,6 +891,7 @@ export const evalToolRenderer = {
 							width,
 							codeMaxLines: EVAL_DEFAULT_PREVIEW_LINES,
 							expanded: true,
+							animate,
 						},
 						uiTheme,
 					);
@@ -951,7 +954,8 @@ export const evalToolRenderer = {
 				render: (width: number): string[] => {
 					const expanded = options.renderContext?.expanded ?? options.expanded;
 					const previewLines = options.renderContext?.previewLines ?? EVAL_DEFAULT_PREVIEW_LINES;
-					const key = `${expanded}|${previewLines}|${options.spinnerFrame}`;
+					const animate = options.isPartial && shimmerEnabled();
+					const key = `${expanded}|${previewLines}|${options.spinnerFrame}|${animate ? borderShimmerTick() : 0}`;
 					if (cached && cached.key === key && cached.width === width) {
 						return cached.result;
 					}
@@ -988,6 +992,7 @@ export const evalToolRenderer = {
 								codeMaxLines: expanded ? Number.POSITIVE_INFINITY : EVAL_DEFAULT_PREVIEW_LINES,
 								expanded,
 								width,
+								animate,
 							},
 							uiTheme,
 						);

package/src/tools/index.ts

@@ -11,6 +11,7 @@ import type { GoalModeState, GoalRuntime } from "../goals";
 import { GoalTool } from "../goals/tools/goal-tool";
 import type { HindsightSessionState } from "../hindsight/state";
 import { LspTool } from "../lsp";
+import type { MnemosyneSessionState } from "../mnemosyne/state";
 import type { PlanModeState } from "../plan-mode/state";
 import { type AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
@@ -33,15 +34,15 @@ import { DebugTool } from "./debug";
 import { EvalTool } from "./eval";
 import { FindTool } from "./find";
 import { GithubTool } from "./gh";
-import { HindsightRecallTool } from "./hindsight-recall";
-import { HindsightReflectTool } from "./hindsight-reflect";
-import { HindsightRetainTool } from "./hindsight-retain";
 import { InspectImageTool } from "./inspect-image";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
+import { MemoryEditTool } from "./memory-edit";
+import { MemoryRecallTool } from "./memory-recall";
+import { MemoryReflectTool } from "./memory-reflect";
+import { MemoryRetainTool } from "./memory-retain";
 import { wrapToolWithMetaNotice } from "./output-meta";
 import { ReadTool } from "./read";
-import { RecipeTool } from "./recipe";
 import { RenderMermaidTool } from "./render-mermaid";
 import { createReportToolIssueTool, isAutoQaEnabled } from "./report-tool-issue";
 import { ResolveTool } from "./resolve";
@@ -73,15 +74,15 @@ export * from "./debug";
 export * from "./eval";
 export * from "./find";
 export * from "./gh";
-export * from "./hindsight-recall";
-export * from "./hindsight-reflect";
-export * from "./hindsight-retain";
 export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./memory-edit";
+export * from "./memory-recall";
+export * from "./memory-reflect";
+export * from "./memory-retain";
 export * from "./read";
-export * from "./recipe";
 export * from "./render-mermaid";
 export * from "./report-tool-issue";
 export * from "./resolve";
@@ -152,6 +153,8 @@ export interface ToolSession {
 	getSessionId?: () => string | null;
 	/** Get Hindsight runtime state for this agent session. */
 	getHindsightSessionState?: () => HindsightSessionState | undefined;
+	/** Get Mnemosyne runtime state for this agent session. */
+	getMnemosyneSessionState?: () => MnemosyneSessionState | undefined;
 	/** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
 	getAgentId?: () => string | null;
 	/** Look up a registered tool by name (used by the eval js backend's tool bridge). */
@@ -295,15 +298,15 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	rewind: RewindTool.createIf,
 	task: s => TaskTool.create(s),
 	job: JobTool.createIf,
-	recipe: RecipeTool.createIf,
 	irc: IrcTool.createIf,
 	todo_write: s => new TodoWriteTool(s),
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
 	write: s => new WriteTool(s),
-	retain: HindsightRetainTool.createIf,
-	recall: HindsightRecallTool.createIf,
-	reflect: HindsightReflectTool.createIf,
+	memory_edit: MemoryEditTool.createIf,
+	retain: MemoryRetainTool.createIf,
+	recall: MemoryRecallTool.createIf,
+	reflect: MemoryReflectTool.createIf,
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
@@ -410,14 +413,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		) {
 			requestedTools.push("ast_edit");
 		}
-		if (
-			requestedTools.includes("bash") &&
-			!requestedTools.includes("recipe") &&
-			session.settings.get("recipe.enabled")
-		) {
-			requestedTools.push("recipe");
-		}
-		if (session.settings.get("memory.backend") === "hindsight") {
+		if (["hindsight", "mnemosyne"].includes(session.settings.get("memory.backend") ?? "")) {
 			for (const name of ["recall", "retain", "reflect"]) {
 				if (!requestedTools.includes(name)) requestedTools.push(name);
 			}
@@ -461,9 +457,8 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 			if (!session.settings.get("async.enabled") && session.getAgentId?.() === MAIN_AGENT_ID) return false;
 			return true;
 		}
-		if (name === "recipe") return session.settings.get("recipe.enabled");
 		if (name === "retain" || name === "recall" || name === "reflect") {
-			return session.settings.get("memory.backend") === "hindsight";
+			return ["hindsight", "mnemosyne"].includes(session.settings.get("memory.backend") ?? "");
 		}
 		if (name === "task") {
 			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;

package/src/tools/memory-edit.ts

@@ -0,0 +1,59 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+import memoryEditDescription from "../prompts/tools/memory-edit.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const memoryEditSchema = z.object({
+	op: z.enum(["update", "forget", "invalidate"]).describe("memory edit operation"),
+	id: z.string().describe("memory id from recall output"),
+	content: z.string().optional().describe("replacement content for update"),
+	importance: z.number().optional().describe("replacement importance for update, clamped to [0, 1]"),
+	replacement_id: z.string().optional().describe("replacement memory id for invalidate"),
+});
+
+export type MemoryEditParams = z.infer<typeof memoryEditSchema>;
+
+export class MemoryEditTool implements AgentTool<typeof memoryEditSchema> {
+	readonly name = "memory_edit";
+	readonly approval = "read" as const;
+	readonly label = "Memory Edit";
+	readonly description = memoryEditDescription;
+	readonly parameters = memoryEditSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly summary = "Update, forget, or invalidate Mnemosyne memories";
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): MemoryEditTool | null {
+		const backend = session.settings.get("memory.backend");
+		if (backend !== "mnemosyne") return null;
+		return new MemoryEditTool(session);
+	}
+
+	async execute(_id: string, params: MemoryEditParams): Promise<AgentToolResult> {
+		const state = this.session.getMnemosyneSessionState?.();
+		if (!state) {
+			throw new Error("Mnemosyne backend is not initialised for this session.");
+		}
+		if (params.op === "update" && params.content === undefined && params.importance === undefined) {
+			throw new Error("memory_edit update requires content or importance.");
+		}
+
+		const importance = params.importance === undefined ? undefined : Math.max(0, Math.min(1, params.importance));
+		const result = state.editScopedMemory(params.op, params.id, {
+			content: params.content,
+			importance,
+			replacementId: params.replacement_id,
+		});
+		const location = result.bank ? ` in bank ${result.bank}${result.store ? ` (${result.store})` : ""}` : "";
+		const text =
+			result.status === "not_found"
+				? `Memory ${params.id} was not found${location}.`
+				: `Memory ${params.id} ${result.status}${location}.`;
+		return {
+			content: [{ type: "text", text }],
+			details: result,
+		};
+	}
+}

package/src/tools/memory-recall.ts

@@ -0,0 +1,100 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import * as z from "zod/v4";
+import { formatCurrentTime, formatMemories } from "../hindsight/content";
+import recallDescription from "../prompts/tools/recall.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const memoryRecallSchema = z.object({
+	query: z.string().describe("natural language search query"),
+});
+
+export type MemoryRecallParams = z.infer<typeof memoryRecallSchema>;
+
+export class MemoryRecallTool implements AgentTool<typeof memoryRecallSchema> {
+	readonly name = "recall";
+	readonly approval = "read" as const;
+	readonly label = "Recall";
+	readonly description = recallDescription;
+	readonly parameters = memoryRecallSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly summary = "Search memory for relevant prior context";
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): MemoryRecallTool | null {
+		const backend = session.settings.get("memory.backend");
+		if (backend !== "hindsight" && backend !== "mnemosyne") return null;
+		return new MemoryRecallTool(session);
+	}
+
+	async execute(_id: string, params: MemoryRecallParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const backend = this.session.settings.get("memory.backend");
+			if (backend === "mnemosyne") {
+				const state = this.session.getMnemosyneSessionState?.();
+				if (!state) {
+					throw new Error("Mnemosyne backend is not initialised for this session.");
+				}
+				try {
+					const results = state.recallResultsScoped(params.query);
+					if (results.length === 0) {
+						return {
+							content: [{ type: "text", text: "No relevant memories found." }],
+							details: {},
+						};
+					}
+					const formatted = state.formatScopedRecallWithIds(results);
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Found ${results.length} relevant ${results.length === 1 ? "memory" : "memories"} (as of ${formatCurrentTime()} UTC):\n\n${formatted}`,
+							},
+						],
+						details: {},
+					};
+				} catch (err) {
+					logger.warn("recall failed", { backend: "mnemosyne", bank: state.config.bank, error: String(err) });
+					throw err instanceof Error ? err : new Error(String(err));
+				}
+			}
+
+			const state = this.session.getHindsightSessionState?.();
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				const response = await state.client.recall(state.bankId, params.query, {
+					budget: state.config.recallBudget,
+					maxTokens: state.config.recallMaxTokens,
+					types: state.config.recallTypes.length > 0 ? state.config.recallTypes : undefined,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const results = response.results ?? [];
+				if (results.length === 0) {
+					return {
+						content: [{ type: "text", text: "No relevant memories found." }],
+						details: {},
+					};
+				}
+				const formatted = formatMemories(results);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Found ${results.length} relevant ${results.length === 1 ? "memory" : "memories"} (as of ${formatCurrentTime()} UTC):\n\n${formatted}`,
+						},
+					],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("recall failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}

package/src/tools/memory-reflect.ts

@@ -0,0 +1,88 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import * as z from "zod/v4";
+import { ensureBankMission } from "../hindsight/bank";
+import reflectDescription from "../prompts/tools/reflect.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const memoryReflectSchema = z.object({
+	query: z.string().describe("question to answer"),
+	context: z.string().describe("optional context").optional(),
+});
+
+export type MemoryReflectParams = z.infer<typeof memoryReflectSchema>;
+
+export class MemoryReflectTool implements AgentTool<typeof memoryReflectSchema> {
+	readonly name = "reflect";
+	readonly approval = "read" as const;
+	readonly label = "Reflect";
+	readonly description = reflectDescription;
+	readonly parameters = memoryReflectSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly summary = "Synthesize an answer from long-term memory";
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): MemoryReflectTool | null {
+		const backend = session.settings.get("memory.backend");
+		if (backend !== "hindsight" && backend !== "mnemosyne") return null;
+		return new MemoryReflectTool(session);
+	}
+
+	async execute(_id: string, params: MemoryReflectParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const backend = this.session.settings.get("memory.backend");
+			if (backend === "mnemosyne") {
+				const state = this.session.getMnemosyneSessionState?.();
+				if (!state) {
+					throw new Error("Mnemosyne backend is not initialised for this session.");
+				}
+
+				try {
+					const query = params.context?.trim()
+						? `${params.query.trim()}\n\nAdditional context:\n${params.context.trim()}`
+						: params.query;
+					const results = state.recallResultsScoped(query);
+					if (results.length === 0) {
+						return {
+							content: [{ type: "text", text: "No relevant information found to reflect on." }],
+							details: {},
+						};
+					}
+					const summary = state.formatContextScoped(results);
+					return {
+						content: [{ type: "text", text: `Based on recalled memories:\n\n${summary}` }],
+						details: {},
+					};
+				} catch (err) {
+					logger.warn("reflect failed", { backend: "mnemosyne", bank: state.config.bank, error: String(err) });
+					throw err instanceof Error ? err : new Error(String(err));
+				}
+			}
+
+			const state = this.session.getHindsightSessionState?.();
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				await ensureBankMission(state.client, state.bankId, state.config, state.missionsSet);
+				const response = await state.client.reflect(state.bankId, params.query, {
+					context: params.context,
+					budget: state.config.recallBudget,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const text = response.text?.trim() || "No relevant information found to reflect on.";
+				return {
+					content: [{ type: "text", text }],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("reflect failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}