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

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

@@ -17,6 +17,15 @@ 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 {
+	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";
@@ -573,7 +582,7 @@ export class CommandController {
 		const backend = resolveMemoryBackend(this.ctx.settings);
 
 		if (action === "view") {
-			const payload = await backend.buildDeveloperInstructions(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 (memory backend off, disabled, or no memory available).");
 				return;
@@ -590,7 +599,7 @@ export class CommandController {
 
 		if (action === "reset" || action === "clear") {
 			try {
-				await backend.clear(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) {
@@ -601,7 +610,7 @@ export class CommandController {
 
 		if (action === "enqueue" || action === "rebuild") {
 			try {
-				await backend.enqueue(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)}`);
@@ -609,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/prompts/tools/hashline.md

@@ -79,4 +79,5 @@ This format is purely textual. The tool has NO awareness of language, indentatio
 - 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 `{{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/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,
@@ -216,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". */
@@ -968,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,
@@ -1335,7 +1339,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const promptTools = buildSystemPromptToolMetadata(tools, {
 				search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
 			});
-			const memoryInstructions = await resolveMemoryBackend(settings).buildDeveloperInstructions(agentDir, settings);
+			const memoryInstructions = await resolveMemoryBackend(settings).buildDeveloperInstructions(
+				agentDir,
+				settings,
+				session,
+			);
 
 			// Build combined append prompt: memory instructions + MCP server instructions
 			const serverInstructions = mcpManager?.getServerInstructions();
@@ -1755,6 +1763,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					modelRegistry,
 					agentDir,
 					taskDepth,
+					parentHindsightSessionState: options.parentHindsightSessionState,
 				}),
 			),
 		);

package/src/session/agent-session.ts

@@ -102,6 +102,7 @@ import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
+import type { HindsightSessionState } from "../hindsight/state";
 import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import {
 	buildDiscoverableMCPSearchIndex,
@@ -563,6 +564,7 @@ export class AgentSession {
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
 	#providerSessionState = new Map<string, ProviderSessionState>();
+	#hindsightSessionState: HindsightSessionState | undefined = undefined;
 
 	#startPowerAssertion(): void {
 		if (process.platform !== "darwin") {
@@ -702,6 +704,16 @@ export class AgentSession {
 		return this.#providerSessionState;
 	}
 
+	getHindsightSessionState(): HindsightSessionState | undefined {
+		return this.#hindsightSessionState;
+	}
+
+	setHindsightSessionState(state: HindsightSessionState | undefined): HindsightSessionState | undefined {
+		const previous = this.#hindsightSessionState;
+		this.#hindsightSessionState = state;
+		return previous;
+	}
+
 	/** TTSR manager for time-traveling stream rules */
 	get ttsrManager(): TtsrManager | undefined {
 		return this.#ttsrManager;
@@ -1964,6 +1976,22 @@ export class AgentSession {
 		this.#unsubscribeAgent = this.agent.subscribe(this.#handleAgentEvent);
 	}
 
+	/** Keep Hindsight metadata aligned when the underlying agent session id changes. */
+	#rekeyHindsightMemoryForCurrentSessionId(): void {
+		if (resolveMemoryBackend(this.settings).id !== "hindsight") return;
+		const sid = this.agent.sessionId;
+		if (!sid) return;
+		this.getHindsightSessionState()?.setSessionId(sid);
+	}
+
+	/** New session file: reset auto-recall / retain-threshold counters for the new transcript. */
+	#resetHindsightConversationTrackingIfHindsight(): void {
+		if (resolveMemoryBackend(this.settings).id !== "hindsight") return;
+		const state = this.getHindsightSessionState();
+		if (!state || state.aliasOf) return;
+		state.resetConversationTracking();
+	}
+
 	/**
 	 * Remove all listeners, flush pending writes, and disconnect from agent.
 	 * Call this when completely done with the session.
@@ -1994,6 +2022,9 @@ export class AgentSession {
 		this.#stopPowerAssertion();
 		await this.sessionManager.close();
 		this.#closeAllProviderSessions("dispose");
+		const hindsightState = this.setHindsightSessionState(undefined);
+		await hindsightState?.flushRetainQueue();
+		hindsightState?.dispose();
 		this.#disconnectFromAgent();
 		this.#eventListeners = [];
 	}
@@ -3626,6 +3657,8 @@ export class AgentSession {
 		await this.sessionManager.newSession(options);
 		this.setTodoPhases([]);
 		this.agent.sessionId = this.sessionManager.getSessionId();
+		this.#rekeyHindsightMemoryForCurrentSessionId();
+		this.#resetHindsightConversationTrackingIfHindsight();
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
 		this.#pendingNextTurnMessages = [];
@@ -3719,6 +3752,7 @@ export class AgentSession {
 
 		// Update agent session ID
 		this.agent.sessionId = this.sessionManager.getSessionId();
+		this.#rekeyHindsightMemoryForCurrentSessionId();
 
 		// Emit session_switch event with reason "fork" to hooks
 		if (this.#extensionRunner) {
@@ -4261,7 +4295,7 @@ export class AgentSession {
 		if (!backend.preCompactionContext) return undefined;
 		const messages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
 		try {
-			return await backend.preCompactionContext(messages, this.settings);
+			return await backend.preCompactionContext(messages, this.settings, this);
 		} catch (err) {
 			logger.debug("Memory backend preCompactionContext failed", {
 				backend: backend.id,
@@ -4425,6 +4459,8 @@ export class AgentSession {
 			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
 			this.agent.reset();
 			this.agent.sessionId = this.sessionManager.getSessionId();
+			this.#rekeyHindsightMemoryForCurrentSessionId();
+			this.#resetHindsightConversationTrackingIfHindsight();
 			this.#steeringMessages = [];
 			this.#followUpMessages = [];
 			this.#pendingNextTurnMessages = [];
@@ -6571,6 +6607,7 @@ export class AgentSession {
 		try {
 			await this.sessionManager.setSessionFile(sessionPath);
 			this.agent.sessionId = this.sessionManager.getSessionId();
+			this.#rekeyHindsightMemoryForCurrentSessionId();
 
 			const sessionContext = this.buildDisplaySessionContext();
 			const didReloadConversationChange =
@@ -6640,11 +6677,15 @@ export class AgentSession {
 					? undefined
 					: configuredServiceTier;
 
+			if (switchingToDifferentSession) {
+				this.#resetHindsightConversationTrackingIfHindsight();
+			}
 			this.#reconnectToAgent();
 			return true;
 		} catch (error) {
 			this.sessionManager.restoreState(previousSessionState);
 			this.agent.sessionId = previousSessionState.sessionId;
+			this.#rekeyHindsightMemoryForCurrentSessionId();
 			let restoreMcpError: unknown;
 			try {
 				await this.#restoreMCPSelectionsForSessionContext(previousSessionContext, {
@@ -6736,6 +6777,8 @@ export class AgentSession {
 		}
 		this.#syncTodoPhasesFromBranch();
 		this.agent.sessionId = this.sessionManager.getSessionId();
+		this.#rekeyHindsightMemoryForCurrentSessionId();
+		this.#resetHindsightConversationTrackingIfHindsight();
 
 		// Reload messages from entries (works for both file and in-memory mode)
 		const sessionContext = this.buildDisplaySessionContext();

package/src/slash-commands/builtin-registry.ts

@@ -598,6 +598,16 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<BuiltinSlashCommandSpec> = [
 			{ name: "reset", description: "Alias for clear" },
 			{ name: "enqueue", description: "Enqueue memory consolidation maintenance" },
 			{ name: "rebuild", description: "Alias for enqueue" },
+			{ name: "mm list", description: "List mental models on the active bank" },
+			{ name: "mm show", description: "Show one mental model (id required)" },
+			{
+				name: "mm refresh",
+				description: "Refresh auto-refresh models bank-wide, or one model by id",
+			},
+			{ name: "mm history", description: "Diff the change history of a mental model" },
+			{ name: "mm seed", description: "Create any built-in mental models that are missing" },
+			{ name: "mm delete", description: "Delete a mental model from the bank (id required)" },
+			{ name: "mm reload", description: "Re-pull the cached <mental_models> block" },
 		],
 		allowArgs: true,
 		handle: async (command, runtime) => {

package/src/task/executor.ts

@@ -17,6 +17,7 @@ import { SETTINGS_SCHEMA, type SettingPath } from "../config/settings-schema";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import { runExtensionCompact, runExtensionSetModel } from "../extensibility/extensions/compact-handler";
 import type { Skill } from "../extensibility/skills";
+import type { HindsightSessionState } from "../hindsight/state";
 import type { LocalProtocolOptions } from "../internal-urls";
 import { callTool } from "../mcp/client";
 import type { MCPManager } from "../mcp/manager";
@@ -163,6 +164,7 @@ export interface ExecutorOptions {
 	settings?: Settings;
 	/** Override local:// protocol options so subagent shares parent's local:// root */
 	localProtocolOptions?: LocalProtocolOptions;
+	parentHindsightSessionState?: HindsightSessionState;
 }
 
 function parseStringifiedJson(value: unknown): unknown {
@@ -979,6 +981,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				hasUI: false,
 				spawns: spawnsEnv,
 				taskDepth: childDepth,
+				parentHindsightSessionState: options.parentHindsightSessionState,
 				parentTaskPrefix: id,
 				agentId: id,
 				agentDisplayName: agent.name,

package/src/task/index.ts

@@ -864,6 +864,7 @@ export class TaskTool implements AgentTool<TSchema, TaskToolDetails, Theme> {
 						skills: availableSkills,
 						promptTemplates,
 						localProtocolOptions,
+						parentHindsightSessionState: this.session.getHindsightSessionState?.(),
 					});
 				}
 
@@ -918,6 +919,7 @@ export class TaskTool implements AgentTool<TSchema, TaskToolDetails, Theme> {
 						skills: availableSkills,
 						promptTemplates,
 						localProtocolOptions,
+						parentHindsightSessionState: this.session.getHindsightSessionState?.(),
 					});
 					if (mergeMode === "branch" && result.exitCode === 0) {
 						try {

package/src/tools/hindsight-recall.ts

@@ -1,7 +1,6 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { logger, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { getHindsightSessionState } from "../hindsight/backend";
 import { formatCurrentTime, formatMemories } from "../hindsight/content";
 import recallDescription from "../prompts/tools/recall.md" with { type: "text" };
 import type { ToolSession } from ".";
@@ -30,8 +29,7 @@ export class HindsightRecallTool implements AgentTool<typeof hindsightRecallSche
 
 	async execute(_id: string, params: HindsightRecallParams, signal?: AbortSignal): Promise<AgentToolResult> {
 		return untilAborted(signal, async () => {
-			const sessionId = this.session.getSessionId?.();
-			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			const state = this.session.getHindsightSessionState?.();
 			if (!state) {
 				throw new Error("Hindsight backend is not initialised for this session.");
 			}

package/src/tools/hindsight-reflect.ts

@@ -1,7 +1,6 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { logger, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { getHindsightSessionState } from "../hindsight/backend";
 import { ensureBankMission } from "../hindsight/bank";
 import reflectDescription from "../prompts/tools/reflect.md" with { type: "text" };
 import type { ToolSession } from ".";
@@ -29,8 +28,7 @@ export class HindsightReflectTool implements AgentTool<typeof hindsightReflectSc
 
 	async execute(_id: string, params: HindsightReflectParams, signal?: AbortSignal): Promise<AgentToolResult> {
 		return untilAborted(signal, async () => {
-			const sessionId = this.session.getSessionId?.();
-			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			const state = this.session.getHindsightSessionState?.();
 			if (!state) {
 				throw new Error("Hindsight backend is not initialised for this session.");
 			}

package/src/tools/hindsight-retain.ts

@@ -1,7 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { type Static, Type } from "@sinclair/typebox";
-import { getHindsightSessionState } from "../hindsight/backend";
-import { enqueueRetain } from "../hindsight/retain-queue";
 import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
 import type { ToolSession } from ".";
 
@@ -39,18 +37,17 @@ export class HindsightRetainTool implements AgentTool<typeof hindsightRetainSche
 	}
 
 	async execute(_id: string, params: HindsightRetainParams): Promise<AgentToolResult> {
-		const sessionId = this.session.getSessionId?.();
-		const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
-		if (!state || !sessionId) {
+		const state = this.session.getHindsightSessionState?.();
+		if (!state) {
 			throw new Error("Hindsight backend is not initialised for this session.");
 		}
 
-		// Push every item onto the global queue and return immediately. The
-		// queue flushes either when it reaches its batch threshold or when its
-		// debounce timer fires. If the eventual batch fails, the queue
+		// Push every item onto the session-owned queue and return immediately.
+		// The queue flushes either when it reaches its batch threshold or when
+		// its debounce timer fires. If the eventual batch fails, the queue
 		// surfaces a UI-only warning notice — the LLM is not informed.
 		for (const item of params.items) {
-			enqueueRetain(sessionId, item.content, item.context);
+			state.enqueueRetain(item.content, item.context);
 		}
 
 		const count = params.items.length;

package/src/tools/index.ts

@@ -7,6 +7,7 @@ import type { Settings } from "../config/settings";
 import { EditTool } from "../edit";
 import { checkPythonKernelAvailability } from "../eval/py/kernel";
 import type { Skill } from "../extensibility/skills";
+import type { HindsightSessionState } from "../hindsight/state";
 import type { InternalUrlRouter } from "../internal-urls";
 import { LspTool } from "../lsp";
 import type { DiscoverableMCPSearchIndex, DiscoverableMCPTool } from "../mcp/discoverable-tool-metadata";
@@ -141,6 +142,8 @@ export interface ToolSession {
 	trackEvalExecution?<T>(execution: Promise<T>, abortController: AbortController): Promise<T>;
 	/** Get session ID */
 	getSessionId?: () => string | null;
+	/** Get Hindsight runtime state for this agent session. */
+	getHindsightSessionState?: () => HindsightSessionState | 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). */