pi-observational-memory 2.3.0 → 2.4.0

package/src/tools/recall-observation.ts

@@ -4,27 +4,30 @@ import { defineTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { Text } from "@mariozechner/pi-tui";
 import {
-	recallObservationSources,
+	recallMemorySources,
 	type Entry,
-	type RecallObservationMatch,
-	type RecallObservationSourcesResult,
+	type RecallMemoryObservation,
+	type RecallMemorySourcesResult,
 } from "../branch.js";
 import { renderRecallSourceEntries, renderRecallSourceEntry } from "../serialize.js";
 import { estimateEntryTokens } from "../tokens.js";
-import type { ObservationRecord } from "../types.js";
+import type { ObservationRecord, ReflectionRecord } from "../types.js";
 
 export const RECALL_OBSERVATION_TOOL_NAME = "recall";
 
-const OBSERVATION_ID_PATTERN = /^[a-f0-9]{12}$/;
+const MEMORY_ID_PATTERN = /^[a-f0-9]{12}$/;
 
 type RecallObservationToolStatus =
 	| "ok"
+	| "partial"
 	| "invalid_id"
 	| "not_found"
 	| "no_source"
-	| "source_unavailable";
+	| "source_unavailable"
+	| "no_provenance";
 
 type ObservationDetails = Pick<ObservationRecord, "id" | "content" | "timestamp" | "relevance">;
+type ReflectionDetails = Pick<ReflectionRecord, "id" | "content" | "supportingObservationIds" | "legacy"> & { reflectionIndex: number };
 
 export type RecallSourceEntryDetails = {
 	id: string;
@@ -36,8 +39,9 @@ export type RecallSourceEntryDetails = {
 };
 
 type RecallObservationMatchDetails = {
-	status: RecallObservationMatch["status"];
+	status: RecallMemoryObservation["status"];
 	observationEntryId: string;
+	observationRecordIndex: number;
 	observation: ObservationDetails;
 	sourceEntryIds?: string[];
 	sourceEntries?: RecallSourceEntryDetails[];
@@ -46,11 +50,33 @@ type RecallObservationMatchDetails = {
 	sourceCharacterCount?: number;
 };
 
+type RecallUnavailableSupportingObservationDetails = {
+	reflectionId: string;
+	reflectionIndex: number;
+	observationId: string;
+};
+
+type RecallUnavailableReflectionProvenanceDetails = {
+	reflectionId: string;
+	reflectionIndex: number;
+	reason: "legacy";
+};
+
 export type RecallObservationToolDetails = {
 	status: RecallObservationToolStatus;
+	memoryId: string;
 	observationId: string;
 	collision: boolean;
+	partial: boolean;
+	reflections: ReflectionDetails[];
+	directObservationMatches: RecallObservationMatchDetails[];
+	observations: RecallObservationMatchDetails[];
 	matches: RecallObservationMatchDetails[];
+	sourceEntries: RecallSourceEntryDetails[];
+	unavailableSupportingObservations: RecallUnavailableSupportingObservationDetails[];
+	unavailableReflectionProvenance: RecallUnavailableReflectionProvenanceDetails[];
+	missingSourceEntryIds: string[];
+	nonSourceEntryIds: string[];
 	sourceCharacterCount?: number;
 	message?: string;
 };
@@ -143,23 +169,41 @@ function observationDetails(observation: ObservationRecord): ObservationDetails
 	};
 }
 
-function matchDetails(match: RecallObservationMatch, sourceText?: string, includeSourceContent = true): RecallObservationMatchDetails {
+function reflectionDetails(reflection: ReflectionRecord, reflectionIndex: number): ReflectionDetails {
+	return {
+		id: reflection.id,
+		content: reflection.content,
+		supportingObservationIds: reflection.supportingObservationIds,
+		...(reflection.legacy === true ? { legacy: true } : {}),
+		reflectionIndex,
+	};
+}
+
+function observationMatchDetails(match: RecallMemoryObservation, includeSourceContent = true): RecallObservationMatchDetails {
 	if (match.status === "ok") {
 		return {
 			status: "ok",
 			observationEntryId: match.observationEntryId,
+			observationRecordIndex: match.observationRecordIndex,
 			observation: observationDetails(match.observation),
 			sourceEntryIds: match.sourceEntryIds,
 			sourceEntries: match.sourceEntries.map((entry) => sourceEntryDetails(entry, includeSourceContent)),
-			sourceCharacterCount: sourceText?.length ?? 0,
+			sourceCharacterCount: renderRecallSourceEntries(match.sourceEntries).length,
 		};
 	}
 	if (match.status === "source_unavailable") {
 		return {
 			status: "source_unavailable",
 			observationEntryId: match.observationEntryId,
+			observationRecordIndex: match.observationRecordIndex,
 			observation: observationDetails(match.observation),
 			sourceEntryIds: match.sourceEntryIds,
+			...(includeSourceContent
+				? {
+						sourceEntries: match.sourceEntries.map((entry) => sourceEntryDetails(entry, true)),
+						sourceCharacterCount: renderRecallSourceEntries(match.sourceEntries).length,
+					}
+				: {}),
 			missingSourceEntryIds: match.missingSourceEntryIds,
 			nonSourceEntryIds: match.nonSourceEntryIds,
 		};
@@ -167,6 +211,7 @@ function matchDetails(match: RecallObservationMatch, sourceText?: string, includ
 	return {
 		status: "no_source",
 		observationEntryId: match.observationEntryId,
+		observationRecordIndex: match.observationRecordIndex,
 		observation: observationDetails(match.observation),
 	};
 }
@@ -178,59 +223,187 @@ function textResult(text: string, details: RecallObservationToolDetails) {
 	};
 }
 
-function aggregateStatus(matches: RecallObservationMatch[]): RecallObservationToolStatus {
-	if (matches.some((match) => match.status === "ok")) return "ok";
-	if (matches.some((match) => match.status === "source_unavailable")) return "source_unavailable";
-	return "no_source";
+function emptyDetails(status: RecallObservationToolStatus, memoryId: string, message: string): RecallObservationToolDetails {
+	return {
+		status,
+		memoryId,
+		observationId: memoryId,
+		collision: false,
+		partial: false,
+		reflections: [],
+		directObservationMatches: [],
+		observations: [],
+		matches: [],
+		sourceEntries: [],
+		unavailableSupportingObservations: [],
+		unavailableReflectionProvenance: [],
+		missingSourceEntryIds: [],
+		nonSourceEntryIds: [],
+		message,
+	};
+}
+
+function aggregateStatus(details: Omit<RecallObservationToolDetails, "status">): RecallObservationToolStatus {
+	const observationOnly = details.reflections.length === 0 && details.unavailableSupportingObservations.length === 0 && details.unavailableReflectionProvenance.length === 0;
+	if (observationOnly && details.observations.some((match) => match.status === "ok")) return "ok";
+	if (observationOnly && details.observations.some((match) => match.status === "source_unavailable")) return "source_unavailable";
+	if (observationOnly && details.observations.length > 0) return "no_source";
+	if (details.unavailableReflectionProvenance.length > 0 && details.observations.length === 0 && details.sourceEntries.length === 0) return "no_provenance";
+	if (details.partial) return "partial";
+	if (details.sourceEntries.length > 0) return "ok";
+	if (details.reflections.length > 0) return "ok";
+	if (details.observations.length > 0) return "no_source";
+	return "not_found";
 }
 
-function friendlyNoSourceMessage(observationId: string): string {
-	return `Observation ${observationId} has no source entries associated with it. This can happen for legacy observations created before source recall was available.`;
+function friendlyNoSourceMessage(memoryId: string): string {
+	return `Observation ${memoryId} has no source entries associated with it. This can happen for legacy observations created before source recall was available.`;
 }
 
-function friendlySourceUnavailableMessage(match: Extract<RecallObservationMatch, { status: "source_unavailable" }>): string {
-	const missing = match.missingSourceEntryIds.length > 0 ? ` missing: ${match.missingSourceEntryIds.join(", ")}` : "";
-	const nonSource = match.nonSourceEntryIds.length > 0 ? ` non-source: ${match.nonSourceEntryIds.join(", ")}` : "";
+function friendlySourceUnavailableMessage(match: RecallObservationMatchDetails): string {
+	const missing = match.missingSourceEntryIds && match.missingSourceEntryIds.length > 0 ? ` missing: ${match.missingSourceEntryIds.join(", ")}` : "";
+	const nonSource = match.nonSourceEntryIds && match.nonSourceEntryIds.length > 0 ? ` non-source: ${match.nonSourceEntryIds.join(", ")}` : "";
 	return `Observation ${match.observation.id} has source entries associated, but some are unavailable on the current branch or are not source-renderable.${missing}${nonSource}`;
 }
 
-function renderFoundResult(result: Extract<RecallObservationSourcesResult, { status: "found" }>): ReturnType<typeof textResult> {
-	const sections: string[] = [];
-	const detailsMatches: RecallObservationMatchDetails[] = [];
-	let sourceCharacterCount = 0;
+function reflectionLineText(reflection: ReflectionDetails): string {
+	return `[${reflection.id}] ${reflection.content}`;
+}
+
+function observationLineText(observation: ObservationDetails): string {
+	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] ${observation.content}`;
+}
 
+function renderObservationOnlyTextFromResult(result: Extract<RecallMemorySourcesResult, { status: "found" }>): string {
+	const sections: string[] = [];
 	if (result.collision) {
-		sections.push(`Multiple observations share id ${result.observationId}; returning all matching source results from the current branch.`);
+		sections.push(`Multiple observations share id ${result.memoryId}; returning all matching source results from the current branch.`);
 	}
-
-	for (const match of result.matches) {
+	for (const match of result.directObservationMatches) {
 		if (match.status === "ok") {
 			const sourceText = renderRecallSourceEntries(match.sourceEntries);
-			sourceCharacterCount += sourceText.length;
-			detailsMatches.push(matchDetails(match, sourceText));
 			if (sourceText.trim()) sections.push(sourceText);
 			else sections.push(`Observation ${match.observation.id} has source entries associated, but they rendered no text content.`);
 			continue;
 		}
-
 		if (match.status === "source_unavailable") {
-			detailsMatches.push(matchDetails(match));
-			sections.push(friendlySourceUnavailableMessage(match));
+			sections.push(friendlySourceUnavailableMessage(observationMatchDetails(match, false)));
 			continue;
 		}
-
-		detailsMatches.push(matchDetails(match));
 		sections.push(friendlyNoSourceMessage(match.observation.id));
 	}
+	return sections.join("\n\n");
+}
+
+function unavailableSupportingLineText(item: RecallUnavailableSupportingObservationDetails): string {
+	return `Supporting observation ${item.observationId} for reflection ${item.reflectionId} is unavailable on the current branch.`;
+}
+
+function unavailableReflectionProvenanceLineText(item: RecallUnavailableReflectionProvenanceDetails): string {
+	return `Reflection ${item.reflectionId} was migrated from legacy memory created before reflection provenance was recorded, so no supporting observations or raw sources are available.`;
+}
+
+function unavailableObservationSourceLineText(match: RecallMemoryObservation): string {
+	return `Observation ${match.observation.id} has no source entries associated. This can happen for legacy observations created before source recall was available.`;
+}
+
+function renderMemoryText(result: Extract<RecallMemorySourcesResult, { status: "found" }>): string {
+	const sections: string[] = [];
+	if (result.collision) {
+		sections.push(`Memory id ${result.memoryId} matched multiple observations/reflections; returning all available evidence from the current branch.`);
+	}
+	if (result.reflectionMatches.length > 0) {
+		sections.push(`Reflections:\n${result.reflectionMatches.map((match) => reflectionLineText(reflectionDetails(match.reflection, match.reflectionIndex))).join("\n")}`);
+	}
+	if (result.observations.length > 0) {
+		sections.push(`Observations:\n${result.observations.map((match) => observationLineText(match.observation)).join("\n")}`);
+	}
+	if (result.unavailableSupportingObservations.length > 0) {
+		sections.push(
+			`Unavailable supporting observations:\n${result.unavailableSupportingObservations
+				.map((item) => unavailableSupportingLineText({
+					reflectionId: item.reflection.id,
+					reflectionIndex: item.reflectionIndex,
+					observationId: item.observationId,
+				}))
+				.join("\n")}`,
+		);
+	}
+	if (result.unavailableReflectionProvenance.length > 0) {
+		sections.push(
+			`Unavailable reflection provenance:\n${result.unavailableReflectionProvenance
+				.map((item) => unavailableReflectionProvenanceLineText({
+					reflectionId: item.reflection.id,
+					reflectionIndex: item.reflectionIndex,
+					reason: item.reason,
+				}))
+				.join("\n")}`,
+		);
+	}
+	const noSourceObservations = result.observations.filter((match) => match.status === "no_source");
+	if (noSourceObservations.length > 0) {
+		sections.push(`Unavailable observation sources:\n${noSourceObservations.map(unavailableObservationSourceLineText).join("\n")}`);
+	}
+	if (result.missingSourceEntryIds.length > 0 || result.nonSourceEntryIds.length > 0) {
+		const parts: string[] = [];
+		if (result.missingSourceEntryIds.length > 0) parts.push(`missing: ${result.missingSourceEntryIds.join(", ")}`);
+		if (result.nonSourceEntryIds.length > 0) parts.push(`non-source: ${result.nonSourceEntryIds.join(", ")}`);
+		sections.push(`Unavailable source entries: ${parts.join("; ")}`);
+	}
+	const sourceText = renderRecallSourceEntries(result.sourceEntries);
+	if (sourceText.trim()) sections.push(`Sources:\n${sourceText}`);
+	if (sections.length === 0) sections.push(`Memory ${result.memoryId} was found, but no source evidence rendered.`);
+	return sections.join("\n\n");
+}
 
-	const text = sections.join("\n\n");
-	return textResult(text, {
-		status: aggregateStatus(result.matches),
-		observationId: result.observationId,
+function resultDetails(result: Extract<RecallMemorySourcesResult, { status: "found" }>, includeSourceContent = true): RecallObservationToolDetails {
+	const reflections = result.reflectionMatches.map((match) => reflectionDetails(match.reflection, match.reflectionIndex));
+	const memoryLayerRecall = result.reflectionMatches.length > 0 || result.unavailableSupportingObservations.length > 0;
+	const includeObservationSources = (_match: RecallMemoryObservation) => includeSourceContent;
+	const observations = result.observations.map((match) => observationMatchDetails(match, includeObservationSources(match)));
+	const directObservationMatches = result.directObservationMatches.map((match) => observationMatchDetails(match, includeObservationSources(match)));
+	const sourceEntries = memoryLayerRecall ? result.sourceEntries.map((entry) => sourceEntryDetails(entry, includeSourceContent)) : [];
+	const unavailableSupportingObservations = result.unavailableSupportingObservations.map((item) => ({
+		reflectionId: item.reflection.id,
+		reflectionIndex: item.reflectionIndex,
+		observationId: item.observationId,
+	}));
+	const unavailableReflectionProvenance = result.unavailableReflectionProvenance.map((item) => ({
+		reflectionId: item.reflection.id,
+		reflectionIndex: item.reflectionIndex,
+		reason: item.reason,
+	}));
+	const partial = result.partial;
+	const detailWithoutStatus = {
+		memoryId: result.memoryId,
+		observationId: result.memoryId,
 		collision: result.collision,
-		matches: detailsMatches,
-		sourceCharacterCount,
-	});
+		partial,
+		reflections,
+		directObservationMatches,
+		observations,
+		matches: directObservationMatches,
+		sourceEntries,
+		unavailableSupportingObservations,
+		unavailableReflectionProvenance,
+		missingSourceEntryIds: result.missingSourceEntryIds,
+		nonSourceEntryIds: result.nonSourceEntryIds,
+		sourceCharacterCount: renderRecallSourceEntries(result.sourceEntries).length,
+	};
+	return {
+		status: aggregateStatus(detailWithoutStatus),
+		...detailWithoutStatus,
+	};
+}
+
+function isObservationOnly(details: RecallObservationToolDetails): boolean {
+	return details.reflections.length === 0 && details.unavailableSupportingObservations.length === 0 && details.unavailableReflectionProvenance.length === 0;
+}
+
+function renderFoundResult(result: Extract<RecallMemorySourcesResult, { status: "found" }>): ReturnType<typeof textResult> {
+	const details = resultDetails(result);
+	const text = isObservationOnly(details) ? renderObservationOnlyTextFromResult(result) : renderMemoryText(result);
+	return textResult(text, details);
 }
 
 function plural(n: number, singular: string, pluralForm = `${singular}s`): string {
@@ -238,6 +411,7 @@ function plural(n: number, singular: string, pluralForm = `${singular}s`): strin
 }
 
 function sourceEntriesFromDetails(details: RecallObservationToolDetails): RecallSourceEntryDetails[] {
+	if (!isObservationOnly(details)) return details.sourceEntries;
 	return details.matches.flatMap((match) => match.sourceEntries ?? []);
 }
 
@@ -245,40 +419,59 @@ function tokenSummary(tokens: number): string {
 	return `~${tokens.toLocaleString()} ${tokens === 1 ? "token" : "tokens"}`;
 }
 
-function statusIcon(details: RecallObservationToolDetails): string {
-	if (details.status === "ok") return details.collision ? "⚠" : "✓";
-	return "×";
+function isFailureStatus(status: RecallObservationToolStatus): boolean {
+	return status === "invalid_id" || status === "not_found";
 }
 
-function statusSummary(details: RecallObservationToolDetails): string {
-	if (details.status === "invalid_id") return "invalid id";
-	if (details.status === "not_found") return "not found";
-	if (details.status === "source_unavailable") return "source unavailable";
-	if (details.status === "no_source") return "no source";
-	return details.collision ? "recalled · id collision" : "recalled";
+function observationCountForHeader(details: RecallObservationToolDetails): number {
+	return isObservationOnly(details) ? details.matches.length : details.observations.length;
 }
 
 export function formatRecallHeaderForTui(details: RecallObservationToolDetails): string {
-	const parts = [`${statusIcon(details)} ${statusSummary(details)}`];
-	if (details.matches.length > 0) parts.push(plural(details.matches.length, "match", "matches"));
+	if (isFailureStatus(details.status)) return "× failure";
+
+	const parts = ["✓ success"];
+	if (details.reflections.length > 0) parts.push(plural(details.reflections.length, "reflection"));
+	const observations = observationCountForHeader(details);
+	if (observations > 0) parts.push(plural(observations, "observation"));
 	const sources = sourceEntriesFromDetails(details);
-	if (sources.length > 0) parts.push(plural(sources.length, "source entry", "source entries"));
+	if (sources.length > 0) parts.push(plural(sources.length, "source"));
 	const tokens = sources.reduce((sum, source) => sum + source.tokens, 0);
 	if (tokens > 0) parts.push(tokenSummary(tokens));
 	return parts.join(" · ");
 }
 
-function sourceLabel(source: RecallSourceEntryDetails): string {
-	return source.origin ? `${source.origin[0].toLowerCase()}${source.origin.slice(1)}` : "entry";
+const TUI_TYPE_WIDTH = 15;
+const TUI_META_WIDTH = 31;
+
+function alignedRow(type: string, meta: string, text: string): string {
+	return `${type.padEnd(TUI_TYPE_WIDTH)} ${meta.padEnd(TUI_META_WIDTH)} ${text}`.trimEnd();
+}
+
+function sourceTag(source: RecallSourceEntryDetails): string {
+	const origin = source.origin.trim().toLowerCase();
+	if (origin === "user") return "user";
+	if (origin === "assistant") return "assistant";
+	if (origin.startsWith("tool result")) return "tool";
+	if (origin.startsWith("custom message")) return "custom";
+	if (origin.startsWith("branch summary")) return "summary";
+	return origin.split(/[^a-z0-9]+/).find(Boolean) ?? "entry";
 }
 
 function sourceMetadataLine(source: RecallSourceEntryDetails): string {
-	const qualifiers = source.qualifiers.length > 0 ? ` · ${source.qualifiers.join(" · ")}` : "";
-	return `✓ ${sourceLabel(source)} · ${source.timestamp} · entry ${source.id} · ${tokenSummary(source.tokens)}${qualifiers}`;
+	return alignedRow("✓ source", `${source.timestamp} [${sourceTag(source)}]`, tokenSummary(source.tokens));
 }
 
 function observationLine(observation: ObservationDetails): string {
-	return `✓ observation · ${observation.timestamp} · [${observation.relevance}] · ${observation.content}`;
+	return alignedRow("✓ observation", `${observation.timestamp} [${observation.relevance}]`, observation.content);
+}
+
+function reflectionLine(reflection: ReflectionDetails): string {
+	return alignedRow("✓ reflection", "", reflection.content);
+}
+
+function noteLine(kind: string, text: string): string {
+	return alignedRow("• note", `[${kind}]`, text);
 }
 
 function indentContent(content: string): string {
@@ -288,31 +481,46 @@ function indentContent(content: string): string {
 		.join("\n");
 }
 
-function unavailableSourceLine(match: RecallObservationMatchDetails): string {
-	const parts: string[] = [];
-	if (match.missingSourceEntryIds && match.missingSourceEntryIds.length > 0) {
-		parts.push(`missing: ${match.missingSourceEntryIds.join(", ")}`);
+function unavailableEvidenceMessage(details: RecallObservationToolDetails): string {
+	if (details.unavailableReflectionProvenance.length > 0 && details.observations.length === 0) {
+		return "migrated legacy reflection has no supporting observations";
 	}
-	if (match.nonSourceEntryIds && match.nonSourceEntryIds.length > 0) {
-		parts.push(`non-source: ${match.nonSourceEntryIds.join(", ")}`);
-	}
-	return `× source unavailable${parts.length > 0 ? ` · ${parts.join(" · ")}` : ""}`;
+	return "no source entries are available for this memory id";
 }
 
-function matchLines(match: RecallObservationMatchDetails, expanded: boolean): string[] {
-	const lines = [observationLine(match.observation), ""];
-	if (match.status === "ok") {
-		for (const source of match.sourceEntries ?? []) {
-			lines.push(sourceMetadataLine(source));
-			if (expanded && source.content) {
-				lines.push(indentContent(source.content));
-				lines.push("");
-			}
+function pushSourceLines(lines: string[], sources: RecallSourceEntryDetails[], expanded: boolean): void {
+	for (const source of sources) {
+		lines.push(sourceMetadataLine(source));
+		if (expanded && source.content) {
+			lines.push(indentContent(source.content));
+			lines.push("");
 		}
-		return lines;
 	}
-	if (match.status === "source_unavailable") return [...lines, unavailableSourceLine(match)];
-	return [...lines, "× no source · legacy/unattributed observation"];
+}
+
+function memoryRows(details: RecallObservationToolDetails): string[] {
+	if (isObservationOnly(details)) return details.matches.map((match) => observationLine(match.observation));
+	return [
+		...details.reflections.map((reflection) => reflectionLine(reflection)),
+		...details.observations.map((observation) => observationLine(observation.observation)),
+	];
+}
+
+function noteRows(details: RecallObservationToolDetails, sources: RecallSourceEntryDetails[]): string[] {
+	const notes: string[] = [];
+	if (details.status === "invalid_id") {
+		notes.push(noteLine("invalid id", `memory ids must be 12 lowercase hex characters; received ${details.memoryId}`));
+		return notes;
+	}
+	if (details.status === "not_found") {
+		notes.push(noteLine("not found", `no observation or reflection with id ${details.memoryId} was found on the current branch`));
+		return notes;
+	}
+	if (details.collision) notes.push(noteLine("id collision", `multiple memory items share ${details.memoryId}`));
+	if (sources.length === 0 && (details.reflections.length > 0 || details.observations.length > 0 || details.matches.length > 0)) {
+		notes.push(noteLine("unavailable evidence", unavailableEvidenceMessage(details)));
+	}
+	return notes;
 }
 
 export function formatRecallResultForTui(result: AgentToolResult<RecallObservationToolDetails>, expanded: boolean): string {
@@ -325,16 +533,17 @@ export function formatRecallResultForTui(result: AgentToolResult<RecallObservati
 		return text || "recall";
 	}
 
+	const sources = sourceEntriesFromDetails(details);
 	const lines: string[] = [];
-	if (details.matches.length > 0) {
-		for (const match of details.matches) {
-			if (lines.length > 0) lines.push("");
-			lines.push(...matchLines(match, expanded));
-		}
-	} else if (details.message) {
-		lines.push(details.message);
-	}
-	if (!expanded && details.matches.some((match) => match.status === "ok" && (match.sourceEntries?.length ?? 0) > 0)) {
+	const rows = memoryRows(details);
+	const notes = noteRows(details, sources);
+	lines.push(...rows);
+	if (rows.length > 0 && notes.length > 0) lines.push("");
+	lines.push(...notes);
+	if ((rows.length > 0 || notes.length > 0) && sources.length > 0) lines.push("");
+	pushSourceLines(lines, sources, expanded);
+
+	if (!expanded && sources.some((source) => source.content)) {
 		lines.push("", "(Ctrl+O to expand)");
 	}
 	return lines.join("\n").trimEnd();
@@ -354,18 +563,25 @@ export function formatRecallRenderedResultForTui(result: AgentToolResult<RecallO
 
 export const recallObservationTool = defineTool({
 	name: RECALL_OBSERVATION_TOOL_NAME,
-	label: "Recall observation source",
-	description: "Recall exact source entries for an observational-memory observation id on the current branch.",
-	promptSnippet: "Recall exact source entries for a compacted observational-memory observation id.",
+	label: "Recall memory evidence",
+	description:
+		"Recover exact evidence and source context behind a compacted observational-memory observation or reflection id on the current branch. " +
+		"Use when compressed memory is important and original source context is needed before acting.",
+	promptSnippet: "Use recall(<id>) to recover exact source context behind compacted memory observations/reflections when precision matters.",
 	promptGuidelines: [
-		"Use recall when a compacted observation id needs exact source context or the user asks what supports a remembered claim.",
-		"This is not general search: pass a specific observation id from the compacted Observations list.",
-		"Do not call recall for broad transcript browsing or off-branch history.",
+		"Use recall before making an important decision that depends on a compacted observation or reflection whose details are unclear.",
+		"Use recall when you need exact wording, rationale, file paths, commands, errors, commits, user constraints, or provenance behind a remembered claim.",
+		"Use recall when a broad reflection is relevant but you need its supporting observations or raw sources to continue safely.",
+		"Use recall when the user asks why you believe something, what supports a memory, or what was decided earlier.",
+		"Do not use recall as semantic search or transcript browsing; you must already have a specific 12-character memory id.",
+		"Do not recall every id preemptively. Recall only when exact source context will materially improve the next action.",
 	],
 	parameters: Type.Object({
 		id: Type.String({
 			pattern: "^[a-f0-9]{12}$",
-			description: "12-character lowercase hex observational-memory observation id.",
+			description:
+				"12-character lowercase hex observation or reflection id shown in compacted memory, /om-view, or a previous recall result. " +
+				"Must be a specific id; this tool does not search by topic.",
 		}),
 	}),
 	renderCall(args) {
@@ -375,29 +591,17 @@ export const recallObservationTool = defineTool({
 		return new Text(formatRecallRenderedResultForTui(result as AgentToolResult<RecallObservationToolDetails>, options.expanded), 0, 0);
 	},
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-		const observationId = params.id;
-		if (!OBSERVATION_ID_PATTERN.test(observationId)) {
-			const message = `Observation id must be 12 lowercase hex characters. Received: ${observationId}`;
-			return textResult(message, {
-				status: "invalid_id",
-				observationId,
-				collision: false,
-				matches: [],
-				message,
-			});
+		const memoryId = params.id;
+		if (!MEMORY_ID_PATTERN.test(memoryId)) {
+			const message = `Memory id must be 12 lowercase hex characters. Received: ${memoryId}`;
+			return textResult(message, emptyDetails("invalid_id", memoryId, message));
 		}
 
 		const branchEntries = ctx.sessionManager.getBranch() as Entry[];
-		const result = recallObservationSources(branchEntries, observationId);
+		const result = recallMemorySources(branchEntries, memoryId);
 		if (result.status === "not_found") {
-			const message = `No observation with id ${observationId} was found on the current branch.`;
-			return textResult(message, {
-				status: "not_found",
-				observationId,
-				collision: false,
-				matches: [],
-				message,
-			});
+			const message = `No observation or reflection with id ${memoryId} was found on the current branch.`;
+			return textResult(message, emptyDetails("not_found", memoryId, message));
 		}
 
 		return renderFoundResult(result);