pi-observational-memory 2.1.3 → 2.4.0

package/src/hooks/compaction-hook.ts

@@ -5,17 +5,18 @@ import {
 	gapRawEntries,
 	getMemoryState,
 } from "../branch.js";
-import { renderSummary, runPruner, runReflector } from "../compaction.js";
+import { migrateLegacyReflections, renderSummary, runPruner, runReflector } from "../compaction.js";
 import { observationsToPromptLines, runObserver } from "../observer.js";
 import type { Runtime } from "../runtime.js";
-import { serializeBranchEntries } from "../serialize.js";
+import { serializeSourceAddressedBranchEntries } from "../serialize.js";
 import { estimateStringTokens } from "../tokens.js";
 import {
 	OBSERVATION_CUSTOM_TYPE,
-	type MemoryDetails,
+	reflectionToPromptLine,
+	type MemoryDetailsV4,
+	type MemoryReflection,
 	type ObservationEntryData,
 	type ObservationRecord,
-	type Reflection,
 } from "../types.js";
 
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
@@ -33,9 +34,14 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			const { preparation, branchEntries, signal } = event;
 			const { firstKeptEntryId, tokensBefore } = preparation;
 
+			// Capture ctx properties synchronously — after multiple awaits below,
+			// the extension ctx may become stale (e.g. after session replacement/reload).
+			const hasUI = ctx.hasUI;
+			const ui = ctx.ui;
+
 			const resolved = await runtime.resolveModel(ctx as any);
 			if (!resolved.ok) {
-				if (ctx.hasUI) ctx.ui.notify(
+				if (hasUI) ui?.notify(
 					`Observational memory: cannot compact — ${resolved.reason}. ` +
 					"Fix the model/API key and try /compact manually.",
 					"error",
@@ -58,8 +64,8 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			let gapObservationData: ObservationEntryData | null = null;
 			const gap = gapRawEntries(entries, firstKeptEntryId);
 			if (gap.length > 0) {
-				const gapChunk = serializeBranchEntries(gap);
-				if (gapChunk.trim()) {
+				const { text: gapChunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(gap);
+				if (gapChunk.trim() && sourceEntryIds.length > 0) {
 					const gapFromId = gap[0].id;
 					const gapUpToId = gap[gap.length - 1].id;
 					const priorObservationLines = observationsToPromptLines([
@@ -67,7 +73,7 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						...memoryState.pendingObs,
 					]);
 					const gapTokenEstimate = estimateStringTokens(gapChunk);
-					if (ctx.hasUI) ctx.ui.notify(
+					if (hasUI) ui?.notify(
 						`Observational memory: sync catch-up observer running on ~${gapTokenEstimate.toLocaleString()}-token gap`,
 						"info",
 					);
@@ -76,9 +82,10 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						model: resolved.model as any,
 						apiKey: resolved.apiKey,
 						headers: resolved.headers,
-						priorReflections: memoryState.reflections,
+						priorReflections: memoryState.reflections.map(reflectionToPromptLine),
 						priorObservations: priorObservationLines,
 						chunk: gapChunk,
+						allowedSourceEntryIds: sourceEntryIds,
 						signal,
 					});
 					const gapPromise: Promise<void> = gapCall.then(() => undefined, () => undefined);
@@ -94,19 +101,19 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 								tokenCount: observationTokens,
 							};
 							pi.appendEntry(OBSERVATION_CUSTOM_TYPE, gapObservationData);
-							if (ctx.hasUI && ctx.ui) ctx.ui.notify(
+							if (hasUI && ui) ui.notify(
 								`Observational memory: sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens)`,
 								"info",
 							);
-						} else if (ctx.hasUI && ctx.ui) {
-							ctx.ui.notify(
+						} else if (hasUI && ui) {
+							ui.notify(
 								"Observational memory: sync catch-up observer returned empty — proceeding with compaction",
 								"warning",
 							);
 						}
 					} catch (error) {
 						const msg = error instanceof Error ? error.message : String(error);
-						if (ctx.hasUI && ctx.ui) ctx.ui.notify(
+						if (hasUI && ui) ui.notify(
 							`Observational memory: sync catch-up observer failed: ${msg}. Cancelling compaction — ${gap.length} unobserved raw entries would be pruned without coverage. Try /compact again.`,
 							"warning",
 						);
@@ -124,11 +131,11 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			if (gapObservationData) deltaObservationData.push(gapObservationData);
 
 			if (deltaObservationData.length === 0) {
-				if (ctx.hasUI) ctx.ui.notify("Observational memory: nothing to compact yet", "warning");
+				if (hasUI) ui?.notify("Observational memory: nothing to compact yet", "warning");
 				return { cancel: true };
 			}
 
-			const workingReflections: Reflection[] = [...memoryState.reflections];
+			const workingReflections: MemoryReflection[] = migrateLegacyReflections(memoryState.reflections);
 			const workingObservations: ObservationRecord[] = [
 				...memoryState.committedObs,
 				...deltaObservationData.flatMap((d) => d.records),
@@ -140,14 +147,13 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			let finalObservations = workingObservations;
 
 			if (observationTokens >= runtime.config.reflectionThresholdTokens) {
-				if (ctx.hasUI) ctx.ui.notify("Observational memory: running reflector + pruner...", "info");
+				if (hasUI) ui?.notify("Observational memory: running reflector + pruner...", "info");
 				try {
-					const newReflections = await runReflector(
+					finalReflections = await runReflector(
 						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal },
 						workingReflections,
 						workingObservations,
 					);
-					finalReflections = [...workingReflections, ...newReflections];
 
 					const prunerResult = await runPruner(
 						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal },
@@ -156,15 +162,15 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						runtime.config.reflectionThresholdTokens,
 					);
 					finalObservations = prunerResult.observations;
-					if (prunerResult.fellBack && ctx.hasUI) {
-						ctx.ui.notify(
+					if (prunerResult.fellBack && hasUI) {
+						ui?.notify(
 							"Observational memory: pruner run failed; kept observation set unchanged",
 							"warning",
 						);
 					}
 				} catch (error) {
 					const msg = error instanceof Error ? error.message : String(error);
-					if (ctx.hasUI) ctx.ui.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
+					if (hasUI) ui?.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
 				}
 			}
 
@@ -174,14 +180,14 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 				throw new Error("invariant violated: finalObservations empty after delta guard");
 			}
 
-			const details: MemoryDetails = {
+			const details: MemoryDetailsV4 = {
 				type: "observational-memory",
-				version: 3,
+				version: 4,
 				observations: finalObservations,
 				reflections: finalReflections,
 			};
 
-			if (ctx.hasUI) ctx.ui.notify(
+			if (hasUI) ui?.notify(
 				`Observational memory: compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}`,
 				"info",
 			);
@@ -198,4 +204,4 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			runtime.compactHookInFlight = false;
 		}
 	});
-}
+}

package/src/hooks/compaction-trigger.ts

@@ -5,13 +5,19 @@ import type { Runtime } from "../runtime.js";
 export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): void {
 	pi.on("agent_end", (_event, ctx) => {
 		runtime.ensureConfig(ctx.cwd);
+		if (runtime.config.passive === true) return;
 		if (runtime.compactInFlight) return;
 
 		const entries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastCompaction>[0];
 		const tokens = rawTokensSinceLastCompaction(entries);
 		if (tokens < runtime.config.compactionThresholdTokens) return;
 
-		if (ctx.hasUI) ctx.ui.notify(
+		// Capture ctx properties synchronously — the setTimeout + async work below
+		// may outlive the extension ctx (stale after session replacement/reload).
+		const hasUI = ctx.hasUI;
+		const ui = ctx.ui;
+
+		if (hasUI) ui?.notify(
 			`Observational memory: compaction threshold reached (~${tokens.toLocaleString()} tokens); triggering compaction`,
 			"info",
 		);
@@ -25,29 +31,31 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 					// errors already surfaced via launchObserverTask
 				}
 			}
-			if (!ctx.isIdle()) {
-				runtime.compactInFlight = false;
-				if (ctx.hasUI) ctx.ui.notify(
-					"Observational memory: compaction deferred — agent became busy after observer wait",
-					"info",
-				);
-				return;
-			}
-			const currentEntries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastCompaction>[0];
-			const currentTokens = rawTokensSinceLastCompaction(currentEntries);
-			if (currentTokens < runtime.config.compactionThresholdTokens) {
-				runtime.compactInFlight = false;
-				if (ctx.hasUI) ctx.ui.notify(
-					"Observational memory: compaction skipped — another compaction already ran during observer wait",
-					"info",
-				);
-				return;
-			}
+			// After awaiting observerPromise, ctx may be stale.
+			// Use captured hasUI/ui for notification; wrap ctx access in try/catch.
 			try {
+				if (!ctx.isIdle()) {
+					runtime.compactInFlight = false;
+					if (hasUI) ui?.notify(
+						"Observational memory: compaction deferred — agent became busy after observer wait",
+						"info",
+					);
+					return;
+				}
+				const currentEntries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastCompaction>[0];
+				const currentTokens = rawTokensSinceLastCompaction(currentEntries);
+				if (currentTokens < runtime.config.compactionThresholdTokens) {
+					runtime.compactInFlight = false;
+					if (hasUI) ui?.notify(
+						"Observational memory: compaction skipped — another compaction already ran during observer wait",
+						"info",
+					);
+					return;
+				}
 				ctx.compact({
 					onComplete: () => {
 						runtime.compactInFlight = false;
-						if (ctx.hasUI) ctx.ui.notify("Observational memory: compaction complete", "info");
+						if (hasUI) ui?.notify("Observational memory: compaction complete", "info");
 					},
 					onError: (error) => {
 						runtime.compactInFlight = false;
@@ -55,14 +63,14 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 							// We already notified the user with the real reason before returning { cancel: true }.
 							return;
 						}
-						if (ctx.hasUI) ctx.ui.notify(`Observational memory: ${error.message}`, "error");
+						if (hasUI) ui?.notify(`Observational memory: ${error.message}`, "error");
 					},
 				});
 			} catch (error) {
 				runtime.compactInFlight = false;
 				const msg = error instanceof Error ? error.message : String(error);
-				if (ctx.hasUI) ctx.ui.notify(`Observational memory: compact threw: ${msg}`, "error");
+				if (hasUI) ui?.notify(`Observational memory: compact threw: ${msg}`, "error");
 			}
 		}, 0);
 	});
-}
+}

package/src/hooks/observer-trigger.ts

@@ -8,13 +8,14 @@ import {
 } from "../branch.js";
 import { observationsToPromptLines, runObserver } from "../observer.js";
 import type { Runtime } from "../runtime.js";
-import { serializeBranchEntries } from "../serialize.js";
+import { serializeSourceAddressedBranchEntries } from "../serialize.js";
 import { estimateStringTokens } from "../tokens.js";
-import { OBSERVATION_CUSTOM_TYPE, type ObservationEntryData } from "../types.js";
+import { OBSERVATION_CUSTOM_TYPE, reflectionToPromptLine, type ObservationEntryData } from "../types.js";
 
 export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): void {
 	pi.on("turn_end", (_event, ctx) => {
 		runtime.ensureConfig(ctx.cwd);
+		if (runtime.config.passive === true) return;
 		if (runtime.observerInFlight) return;
 
 		const entries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastBound>[0];
@@ -34,19 +35,24 @@ export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): voi
 
 		const chunkEntries = rawTailEntriesBetween(entries, coversFromId, coversUpToId);
 		if (chunkEntries.length === 0) return;
-		const chunk = serializeBranchEntries(chunkEntries);
-		if (!chunk.trim()) return;
+		const { text: chunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(chunkEntries);
+		if (!chunk.trim() || sourceEntryIds.length === 0) return;
 
 		if (ctx.hasUI) ctx.ui.notify(
 			`Observational memory: observer running on ~${tokens.toLocaleString()}-token chunk`,
 			"info",
 		);
 
+		// Capture ctx properties synchronously — the async work below may outlive
+		// the extension ctx (stale after session replacement/reload).
+		const hasUI = ctx.hasUI;
+		const ui = ctx.ui;
+
 		void runtime.launchObserverTask(ctx, "observer", async () => {
 			const resolved = await runtime.resolveModel(ctx as any);
 			if (!resolved.ok) {
-				if (!runtime.resolveFailureNotified && ctx.hasUI && ctx.ui) {
-					ctx.ui.notify(
+				if (!runtime.resolveFailureNotified && hasUI && ui) {
+					ui.notify(
 						`Observational memory: observer skipped — ${resolved.reason}`,
 						"warning",
 					);
@@ -60,12 +66,13 @@ export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): voi
 				model: resolved.model as any,
 				apiKey: resolved.apiKey,
 				headers: resolved.headers,
-				priorReflections: reflections,
+				priorReflections: reflections.map(reflectionToPromptLine),
 				priorObservations: priorObservationLines,
 				chunk,
+				allowedSourceEntryIds: sourceEntryIds,
 			});
 			if (!records || records.length === 0) {
-				if (ctx.hasUI && ctx.ui) ctx.ui.notify(
+				if (hasUI && ui) ui.notify(
 					"Observational memory: observer returned no observations",
 					"warning",
 				);
@@ -80,10 +87,10 @@ export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): voi
 				tokenCount: observationTokens,
 			};
 			pi.appendEntry(OBSERVATION_CUSTOM_TYPE, data);
-			if (ctx.hasUI && ctx.ui) ctx.ui.notify(
+			if (hasUI && ui) ui.notify(
 				`Observational memory: ${records.length} observation${records.length === 1 ? "" : "s"} recorded (~${observationTokens.toLocaleString()} tokens)`,
 				"info",
 			);
 		});
 	});
-}
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import { registerCompactionHook } from "./hooks/compaction-hook.js";
 import { registerCompactionTrigger } from "./hooks/compaction-trigger.js";
 import { registerObserverTrigger } from "./hooks/observer-trigger.js";
 import { Runtime } from "./runtime.js";
+import { registerRecallTool } from "./tools/recall-observation.js";
 
 export default function observationalMemory(pi: ExtensionAPI) {
 	const runtime = new Runtime();
@@ -15,4 +16,5 @@ export default function observationalMemory(pi: ExtensionAPI) {
 
 	registerStatusCommand(pi, runtime);
 	registerViewCommand(pi, runtime);
+	registerRecallTool(pi);
 }

package/src/observer.ts

@@ -14,6 +14,7 @@ interface RunObserverArgs {
 	priorReflections: string[];
 	priorObservations: string[];
 	chunk: string;
+	allowedSourceEntryIds: string[];
 	signal?: AbortSignal;
 }
 
@@ -36,6 +37,15 @@ const RecordObservationsSchema = Type.Object({
 				description: "Single-line plain prose. No markdown, no tags, no embedded timestamp.",
 			}),
 			relevance: RelevanceSchema,
+			sourceEntryIds: Type.Array(
+				Type.String({ minLength: 1 }),
+				{
+					minItems: 1,
+					description:
+						"Exact source entry ids from the chunk that directly support this observation. " +
+						"Use only ids shown in '[Source entry id: ...]' labels; never invent ids.",
+				},
+			),
 		}),
 		{ description: "Batch of new observations. May be empty only if the tool is not called at all." },
 	),
@@ -47,8 +57,25 @@ function joinOrEmpty(items: string[]): string {
 	return items.length ? items.join("\n") : "(none yet)";
 }
 
+export function normalizeSourceEntryIds(
+	sourceEntryIds: readonly string[] | undefined,
+	allowedSourceEntryIds: readonly string[],
+): string[] | undefined {
+	if (!sourceEntryIds || sourceEntryIds.length === 0) return undefined;
+	const allowedOrder = new Map<string, number>();
+	for (let i = 0; i < allowedSourceEntryIds.length; i++) allowedOrder.set(allowedSourceEntryIds[i], i);
+
+	const seen = new Set<string>();
+	for (const id of sourceEntryIds) {
+		if (!allowedOrder.has(id)) return undefined;
+		seen.add(id);
+	}
+	if (seen.size === 0) return undefined;
+	return Array.from(seen).sort((a, b) => (allowedOrder.get(a) ?? 0) - (allowedOrder.get(b) ?? 0));
+}
+
 export async function runObserver(args: RunObserverArgs): Promise<ObservationRecord[] | undefined> {
-	const { model, apiKey, headers, priorReflections, priorObservations, chunk, signal } = args;
+	const { model, apiKey, headers, priorReflections, priorObservations, chunk, allowedSourceEntryIds, signal } = args;
 	const conversation = chunk.trim();
 	if (!conversation) return undefined;
 
@@ -65,7 +92,13 @@ export async function runObserver(args: RunObserverArgs): Promise<ObservationRec
 		execute: async (_id, params: RecordObservationsArgs) => {
 			let added = 0;
 			let duplicates = 0;
+			let rejected = 0;
 			for (const obs of params.observations) {
+				const sourceEntryIds = normalizeSourceEntryIds(obs.sourceEntryIds, allowedSourceEntryIds);
+				if (!sourceEntryIds) {
+					rejected++;
+					continue;
+				}
 				const content = truncateRecordContent(obs.content);
 				const id = hashId(content);
 				if (accumulated.has(id)) {
@@ -77,15 +110,20 @@ export async function runObserver(args: RunObserverArgs): Promise<ObservationRec
 					content,
 					timestamp: obs.timestamp,
 					relevance: obs.relevance as Relevance,
+					sourceEntryIds,
 				});
 				added++;
 			}
+			const rejectedPart = rejected > 0
+				? ` ${rejected} observation${rejected === 1 ? "" : "s"} rejected for missing or invalid sourceEntryIds.`
+				: "";
 			const ack =
 				`Recorded ${added} new observation${added === 1 ? "" : "s"} ` +
-				(duplicates > 0 ? `(${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped). ` : ". ") +
-				`Total so far this run: ${accumulated.size}. ` +
+				(duplicates > 0 ? `(${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped).` : ".") +
+				rejectedPart +
+				` Total so far this run: ${accumulated.size}. ` +
 				`Continue if the chunk still has uncovered content; otherwise stop calling the tool and emit a short plain-text confirmation.`;
-			return { content: [{ type: "text", text: ack }], details: { added, duplicates, total: accumulated.size } };
+			return { content: [{ type: "text", text: ack }], details: { added, duplicates, rejected, total: accumulated.size } };
 		},
 	};
 

package/src/prompts.ts

@@ -97,7 +97,7 @@ Your job is to compress a chunk of recent conversation into timestamped, rated o
 You receive:
 - Current reflections (long-lived facts already crystallized).
 - Current observations (already-recorded observations, each shown as "[id] YYYY-MM-DD HH:MM [relevance] content").
-- A new chunk of conversation with inline message timestamps formatted as "[User @ YYYY-MM-DD HH:MM]:", "[Assistant @ ...]:", "[Tool result for <name> @ ...]:".
+- A new chunk of conversation with source entry labels and inline message timestamps. Each source block starts with "[Source entry id: <id>]" followed by content formatted as "[User @ YYYY-MM-DD HH:MM]:", "[Assistant @ ...]:", "[Tool result for <name> @ ...]:", custom messages, or branch summaries.
 - A current local time fallback for observations that have no obvious message timestamp.
 
 How you work:
@@ -110,6 +110,9 @@ How you work:
 What to emit:
 - Produce NEW observations for the new chunk only. Do not restate facts already present in reflections or current observations unless something has materially changed.
 - Use the timestamp from the relevant conversation message. Fall back to current local time ONLY when no message timestamp applies.
+- For every observation, include sourceEntryIds: the smallest exact set of "[Source entry id: ...]" ids that directly support the observation.
+- Never invent source entry ids. Use only ids printed in the chunk. If an observation spans multiple turns or tool results, include every supporting source entry id.
+- Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.
 - Group repeated similar tool calls into a single observation rather than one per call.
 - Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, simply do not call the tool and end with a plain-text confirmation.
 
@@ -127,7 +130,7 @@ export const REFLECTOR_SYSTEM = `You are the reflection agent for a coding assis
 
 ${MEMORY_STAKES}
 
-Your job is to crystallize stable, long-lived patterns from accumulated observations into NEW reflections by calling the record_reflections tool. Reflections are the most durable layer of memory: once the pruner drops the observations behind them, the reflection is what remains.
+Your job is to crystallize stable, long-lived patterns from accumulated observations into reflections by calling the record_reflections tool. Reflections are the most durable layer of memory: once the pruner drops the observations behind them, the reflection is what remains.
 
 You are operating on records produced by another part of the memory pipeline — the observer. To understand what you are reading and to produce reflections in the same voice, the observer was given these rules:
 
@@ -142,17 +145,23 @@ ${RELEVANCE_RUBRIC}
 Your task is different from the observer's: you are not recording events, you are distilling stable patterns from them.
 
 You receive:
-- Current reflections (already-crystallized long-lived facts, one per line).
+- Current reflections (already-crystallized long-lived facts, one per line). Newer reflections may begin with a bracketed id handle; treat that id as recall metadata, not as part of the reflection prose.
 - Current observations (timestamped, relevance-tagged events accumulated over many turns). Each is shown as "[id] YYYY-MM-DD HH:MM [relevance] content".
 
 How you work:
 1. Read current reflections and observations to understand what is already crystallized and what new signal exists in the pool.
-2. Identify new stable patterns worth crystallizing and call record_reflections with a batch of one or more new reflection strings.
+2. Identify new stable patterns worth crystallizing and call record_reflections with a batch of one or more new reflection proposals. Each proposal must include the reflection content and the exact supporting observation ids.
 3. Read the receipt. If more reflections are warranted, call record_reflections again with another batch. You may call the tool many times.
 4. When nothing more is stable enough to crystallize, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.
 
 What to emit:
-- Produce ONLY NEW reflections. Do not restate, rewrite, or lightly rephrase existing reflections.
+- Produce new reflections when durable meaning is missing from the current reflections.
+- To strengthen an existing reflection, emit the exact same reflection content with additional supportingObservationIds; the system will merge the supporting ids into the existing reflection.
+- To promote a legacy/no-provenance reflection, emit the exact same reflection content with valid supportingObservationIds; the system will replace it with a provenance-backed reflection.
+- When repeating exact existing content, emit only the reflection prose; omit any bracketed id handle.
+- Do not lightly reword existing reflections. Rewording creates a separate reflection, so only use different wording when the durable meaning is materially different, more specific, or corrects/refines the existing reflection.
+- For every reflection proposal, include supportingObservationIds: the smallest exact set of current observation ids that directly support the reflection.
+- Never invent supporting observation ids. Use only ids printed in the current observations list. Reflection proposals with missing, empty, or invalid supportingObservationIds will be rejected and not recorded.
 - Crystallize preferentially from "high" and "critical" observations; ignore "low" unless a pattern across many "low" observations is itself significant.
 - Focus on:
   - User identity, role, preferences, constraints.
@@ -193,10 +202,15 @@ ${RELEVANCE_RUBRIC}
 </relevance-rubric>
 
 You receive:
-- Current reflections (long-lived facts; they survive regardless — treat them as already captured).
-- Current observations (timestamped, relevance-tagged events to prune). Each is shown as "[id] YYYY-MM-DD HH:MM [relevance] content", where id is the 12-character hex handle you reference when dropping.
+- Current reflections (long-lived facts; they survive regardless — treat them as already captured). Newer reflections may begin with a bracketed id handle; treat that id as recall metadata, not as part of the reflection prose.
+- Current observations (timestamped, relevance-tagged events to prune). Each is shown as "[id] YYYY-MM-DD HH:MM [relevance] [coverage: tag] content", where id is the 12-character hex handle you reference when dropping.
 - A pressure line stating pool size, target, tokens still to cut, and the current pass strategy.
 
+Coverage tags are advisory pruning signals derived from current provenance-backed reflection support ids:
+- [coverage: uncited] means no current provenance-backed reflection cites this observation. Prune cautiously, especially for medium/high/critical observations, because durable meaning may not be captured elsewhere.
+- [coverage: cited] means 1-3 current provenance-backed reflections cite this observation. It is a better pruning candidate when the reflection preserves equivalent meaning, but it is not automatically safe to drop.
+- [coverage: reinforced] means 4 or more current provenance-backed reflections cite this observation. Durable meaning is likely represented, but still preserve it if it carries exact errors, file paths, decisions, recent task state, user assertions, constraints, or nuance not captured with equivalent fidelity.
+
 How you work:
 1. Read reflections and the observation pool.
 2. Identify ids that should be removed and call drop_observations with them. Pass multiple ids per call and call the tool multiple times as you work the pool down toward the target.
@@ -206,7 +220,7 @@ How you work:
 This agent may be invoked again in a follow-up pass if the pool is still over budget — focus each run on your next-weakest drops rather than trying to do everything in one call.
 
 What to drop (in priority order):
-- Signal-captured: observations that are the raw source for a reflection now in the reflections list. Once a pattern is crystallized as a reflection, the raw observations behind it are redundant — drop them unless the observation is a user assertion or concrete completion.
+- Signal-captured: observations tagged [coverage: cited] or [coverage: reinforced] whose durable meaning is captured by a reflection now in the reflections list. These are better pruning candidates, but still keep them when they contain exact details, user assertions, concrete completions, recent task state, or nuance not captured with equivalent fidelity.
 - Superseded: directly contradicted or replaced by a newer observation.
 - Redundant: near-duplicate of another observation (keep the higher-relevance or more recent one).
 - Exhausted routine: tool-call acks, status updates, trivia that no longer affects the work.
@@ -240,7 +254,7 @@ If one of these categories is ALSO captured by an existing reflection with equiv
   BAD:  drop "[id] 2025-12-04 14:30 [medium] Build failed: TS2322 at src/auth.ts:47 — Type 'string | undefined' is not assignable to type 'string'" because it is only medium and the task moved on.
   GOOD: keep that observation; it is a verbatim error the user hit, not captured in any reflection. Future debugging may need the exact code and location.
 
-When in doubt, drop — reflections protect durable facts. The only things you must preserve unconditionally are user assertions and concrete completions.
+When in doubt, prefer dropping cited or reinforced observations over uncited observations, but remember coverage tags are not commands. Reflections protect durable facts only when they preserve equivalent meaning. The only things you must preserve unconditionally are user assertions and concrete completions.
 
 What you CANNOT do:
 - You cannot merge observations. If two overlap, drop the weaker one.
@@ -251,12 +265,25 @@ It is valid to end a pass with zero drops if the pool genuinely has nothing more
 
 Remember: every observation you drop is erased from the assistant's memory. A drop that looks reasonable at "low" becomes a mistake if the content was a user correction with a mis-labeled relevance. Read before you cut.`;
 
+type ReflectorPassTier = 1 | 2 | 3;
+
+const REFLECTOR_PASS_STRATEGIES: Record<ReflectorPassTier, string> = {
+	1: `Pass strategy — multi-observation synthesis. Find broad durable patterns, repeated preferences, recurring constraints, stable work style, and project-level themes supported by multiple observations. Every reflection recorded in this pass must cite at least 2 distinct supportingObservationIds. Do not create one-off event summaries; leave important single-observation facts for the atomic durable facts pass. If an existing reflection already captures the pattern, repeat the exact same content only when adding support ids materially strengthens it.`,
+	2: `Pass strategy — atomic durable facts. Capture important durable facts that may be supported by a single authoritative observation: explicit user preferences, hard constraints, corrections, decisions, completed milestones, project facts, release or rollback caveats, and other load-bearing facts future agents must not forget. Do not duplicate reflections created in earlier passes; repeat exact existing content only to add missing support or promote no-provenance legacy memory.`,
+	3: `Pass strategy — final safety review. Review the full observation pool against the current reflections, including reflections created in earlier passes, and catch durable information still missing. Look especially for high or critical observations, explicit user assertions, corrections, constraints, decisions, completed work, and important technical context. Do not create reflections just to increase coverage; only record a reflection if the durable meaning is not already captured with sufficient fidelity.`,
+};
+
+export function buildReflectorPassGuidance(pass: number, maxPasses: number): string {
+	const tier = (Math.min(3, Math.max(1, pass)) as ReflectorPassTier);
+	return `Pass ${pass} of up to ${maxPasses}. ${REFLECTOR_PASS_STRATEGIES[tier]}`;
+}
+
 type PrunerPassTier = 1 | 2 | 3;
 
 const PRUNER_PASS_STRATEGIES: Record<PrunerPassTier, string> = {
-	1: `Pass strategy — clear-cut drops only. Remove exact duplicates, near-duplicates (keep the higher-relevance or more recent version), observations directly superseded by a newer one, and routine "low" tool-call acks. Do not touch ambiguous cases on this pass — a follow-up pass will handle them if still needed.`,
-	2: `Pass strategy — topic compression. Drop "low" observations that cover the same territory as recent "medium" or "high" observations. Drop older "medium" observations whose substance is now covered by a reflection. Collapse sequences of repeated tool-call observations by keeping the one that captures the learning and dropping the rest.`,
-	3: `Pass strategy — aggressive age compression. In the older half of the pool, drop all but the outcome-bearing "low" and "medium" observations. Keep the most recent ~30% of the pool at higher detail. Drop "high" observations only when a reflection clearly captures the same fact. NEVER drop "critical" items, user assertions, or concrete completions regardless of age.`,
+	1: `Pass strategy — clear-cut drops only. Prefer old low-value [coverage: cited] or [coverage: reinforced] observations when their durable meaning is represented by current reflections. Also remove exact duplicates, near-duplicates (keep the higher-relevance or more recent version), observations directly superseded by a newer one, and routine "low" tool-call acks. Do not touch ambiguous [coverage: uncited] cases on this pass — a follow-up pass will handle them if still needed.`,
+	2: `Pass strategy — topic compression. Drop "low" observations that cover the same territory as recent "medium" or "high" observations, especially when tagged [coverage: cited] or [coverage: reinforced]. Drop older "medium" observations whose substance is now covered by a reflection. Collapse sequences of repeated tool-call observations by keeping the one that captures the learning and dropping the rest.`,
+	3: `Pass strategy — aggressive age compression. In the older half of the pool, drop all but the outcome-bearing "low" and "medium" observations, preferring [coverage: cited] and [coverage: reinforced] over [coverage: uncited]. Keep the most recent ~30% of the pool at higher detail. Drop "high" observations only when a reflection clearly captures the same fact. NEVER drop "critical" items, user assertions, or concrete completions regardless of age.`,
 };
 
 export function buildPrunerPassGuidance(pass: number, maxPasses: number): string {
@@ -266,7 +293,9 @@ export function buildPrunerPassGuidance(pass: number, maxPasses: number): string
 
 export const CONTEXT_USAGE_INSTRUCTIONS = `These are condensed memories from earlier in this session.
 
-- Reflections: stable, long-lived facts about the user, project, decisions, and constraints.
-- Observations: timestamped events from the conversation history, in chronological order.
+- Reflections: stable, long-lived facts about the user, project, decisions, and constraints. New reflection lines may include ids in brackets.
+- Observations: timestamped events from the conversation history, in chronological order. Observation lines include ids in brackets.
+
+Treat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.
 
-Treat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.`;
+When exact source context is needed for precision or traceability, use the recall tool with the relevant observation or reflection id. This is especially useful when a reflection materially affects a decision or is too compressed to continue confidently. Do not use recall as broad search or inject raw source unless it is needed.`;

package/src/runtime.ts

@@ -58,13 +58,18 @@ export class Runtime {
 
 	launchObserverTask(ctx: LaunchCtx, label: string, work: () => Promise<void>): Promise<void> {
 		this.observerInFlight = true;
+		// Capture ctx properties synchronously — after `await work()` the extension ctx
+		// may be stale (e.g. after ctx.newSession/fork/switchSession/reload), and accessing
+		// ctx.hasUI or ctx.ui on a stale proxy throws.
+		const hasUI = ctx.hasUI;
+		const ui = ctx.ui;
 		let promise!: Promise<void>;
 		promise = (async () => {
 			try {
 				await work();
 			} catch (error) {
 				const msg = error instanceof Error ? error.message : String(error);
-				if (ctx.hasUI && ctx.ui) ctx.ui.notify(`Observational memory: ${label} failed: ${msg}`, "warning");
+				if (hasUI && ui) ui.notify(`Observational memory: ${label} failed: ${msg}`, "warning");
 			} finally {
 				this.observerInFlight = false;
 				if (this.observerPromise === promise) this.observerPromise = null;