pi-observational-memory 2.3.0 → 2.4.1

package/src/compaction.ts

@@ -1,12 +1,15 @@
 import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@mariozechner/pi-agent-core";
 import { Type, type Message, type Model } from "@mariozechner/pi-ai";
 import type { Static } from "@sinclair/typebox";
+import { hashId } from "./ids.js";
 import { observationsToPromptLines } from "./observer.js";
-import { buildPrunerPassGuidance, CONTEXT_USAGE_INSTRUCTIONS, PRUNER_SYSTEM, REFLECTOR_SYSTEM } from "./prompts.js";
+import { buildPrunerPassGuidance, buildReflectorPassGuidance, CONTEXT_USAGE_INSTRUCTIONS, PRUNER_SYSTEM, REFLECTOR_SYSTEM } from "./prompts.js";
 import { truncateRecordContent } from "./serialize.js";
 import { estimateStringTokens } from "./tokens.js";
-import type { ObservationRecord, Reflection } from "./types.js";
+import { reflectionContent, reflectionToPromptLine } from "./types.js";
+import type { MemoryReflection, ObservationRecord, ReflectionRecord } from "./types.js";
 
+const REFLECTOR_MAX_PASSES = 3;
 const PRUNER_MAX_PASSES = 5;
 const PRUNER_TARGET_RATIO = 0.8;
 
@@ -19,79 +22,341 @@ interface LlmArgs {
 	apiKey: string;
 	headers?: Record<string, string>;
 	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
 }
 
-function joinReflectionsOrEmpty(items: Reflection[]): string {
-	return items.length ? items.join("\n") : "(none yet)";
+function joinReflectionsOrEmpty(items: MemoryReflection[]): string {
+	return items.length ? items.map(reflectionToPromptLine).join("\n") : "(none yet)";
 }
 
 function joinObservationsOrEmpty(items: ObservationRecord[]): string {
 	return items.length ? observationsToPromptLines(items).join("\n") : "(none yet)";
 }
 
+export type ObservationCoverageTag = "uncited" | "cited" | "reinforced";
+
+export function deriveObservationCoverageTags(
+	reflections: MemoryReflection[],
+	observations: ObservationRecord[],
+): Map<string, ObservationCoverageTag> {
+	const activeIds = new Set(observations.map((o) => o.id));
+	const counts = new Map<string, number>();
+	for (const observation of observations) counts.set(observation.id, 0);
+
+	for (const reflection of reflections) {
+		if (typeof reflection === "string" || reflection.legacy === true) continue;
+		const citedActiveIds = new Set(reflection.supportingObservationIds.filter((id) => activeIds.has(id)));
+		for (const id of citedActiveIds) counts.set(id, (counts.get(id) ?? 0) + 1);
+	}
+
+	const tags = new Map<string, ObservationCoverageTag>();
+	for (const observation of observations) {
+		const count = counts.get(observation.id) ?? 0;
+		tags.set(observation.id, count === 0 ? "uncited" : count >= 4 ? "reinforced" : "cited");
+	}
+	return tags;
+}
+
+export function renderObservationsForPrunerPrompt(
+	observations: ObservationRecord[],
+	coverageTags: ReadonlyMap<string, ObservationCoverageTag>,
+): string {
+	if (observations.length === 0) return "(none yet)";
+	return observations
+		.map((observation) => {
+			const tag = coverageTags.get(observation.id) ?? "uncited";
+			return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] [coverage: ${tag}] ${observation.content}`;
+		})
+		.join("\n");
+}
+
+export function migrateLegacyReflections(reflections: MemoryReflection[]): MemoryReflection[] {
+	const migrated: MemoryReflection[] = [];
+	const contentToIndex = new Map<string, number>();
+
+	for (const reflection of reflections) {
+		const rawContent = reflectionContent(reflection).trim();
+		const normalizedContent = typeof reflection === "string" ? rawContent.replace(/\s+/g, " ") : rawContent;
+		if (!normalizedContent) {
+			migrated.push(reflection);
+			continue;
+		}
+		const content = truncateRecordContent(normalizedContent);
+
+		const existingIndex = contentToIndex.get(content);
+		if (existingIndex !== undefined) {
+			const existing = migrated[existingIndex];
+			if (typeof existing !== "string" && existing.legacy === true && typeof reflection !== "string" && reflection.legacy !== true) {
+				migrated[existingIndex] = reflection;
+			}
+			continue;
+		}
+
+		if (typeof reflection !== "string") {
+			migrated.push(reflection);
+			contentToIndex.set(content, migrated.length - 1);
+			continue;
+		}
+
+		migrated.push({
+			id: hashId(content),
+			content,
+			supportingObservationIds: [],
+			legacy: true,
+		});
+		contentToIndex.set(content, migrated.length - 1);
+	}
+
+	return migrated;
+}
+
 const RecordReflectionsSchema = Type.Object({
 	reflections: Type.Array(
-		Type.String({
-			minLength: 1,
-			description: "Single-line plain prose reflection. No markdown, no tags, no timestamp, no bullets.",
+		Type.Object({
+			content: Type.String({
+				minLength: 1,
+				description: "Single-line plain prose reflection. No markdown, no tags, no timestamp, no bullets.",
+			}),
+			supportingObservationIds: Type.Array(
+				Type.String({
+					pattern: "^[a-f0-9]{12}$",
+					description: "Exact observation id from the current-observations list that supports this reflection.",
+				}),
+				{
+					minItems: 1,
+					description:
+						"Smallest exact set of current observation ids that directly support this reflection. " +
+						"Use only ids shown in the current observations list; never invent ids.",
+				},
+			),
 		}),
 		{
 			minItems: 1,
-			description: "Batch of new reflections. Each string is one reflection.",
+			description: "Batch of new reflection proposals with their supporting observation ids.",
 		},
 	),
 });
 
 type RecordReflectionsArgs = Static<typeof RecordReflectionsSchema>;
 
-export async function runReflector(
+export function normalizeSupportingObservationIds(
+	supportingObservationIds: readonly string[] | undefined,
+	allowedObservationIds: readonly string[],
+): string[] | undefined {
+	if (!supportingObservationIds || supportingObservationIds.length === 0) return undefined;
+	const allowedOrder = new Map<string, number>();
+	for (let i = 0; i < allowedObservationIds.length; i++) {
+		if (!allowedOrder.has(allowedObservationIds[i])) allowedOrder.set(allowedObservationIds[i], i);
+	}
+
+	const seen = new Set<string>();
+	for (const id of supportingObservationIds) {
+		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 interface ReflectorPassContext {
+	pass: number;
+	maxPasses: number;
+	minSupportingObservationIds: number;
+}
+
+export type ReflectionProposal = {
+	content: string;
+	supportingObservationIds?: readonly string[];
+};
+
+export interface ApplyReflectionProposalsResult {
+	reflections: MemoryReflection[];
+	accepted: number;
+	added: number;
+	merged: number;
+	promoted: number;
+	duplicates: number;
+	unsupported: number;
+}
+
+function reflectorPassContext(pass: number): ReflectorPassContext {
+	return {
+		pass,
+		maxPasses: REFLECTOR_MAX_PASSES,
+		minSupportingObservationIds: pass === 1 ? 2 : 1,
+	};
+}
+
+function reflectionContentKey(reflection: MemoryReflection): string {
+	return reflectionContent(reflection).trim();
+}
+
+function normalizeReflectionProposalContent(content: string): string | undefined {
+	const normalized = truncateRecordContent(content.trim());
+	if (!normalized || /[\r\n]/.test(normalized)) return undefined;
+	return normalized;
+}
+
+function mergeSupportingObservationIds(
+	existing: readonly string[],
+	incoming: readonly string[],
+	allowedObservationIds: readonly string[],
+): string[] | undefined {
+	const allowed = new Set(allowedObservationIds);
+	const historicalExisting = existing.filter((id) => !allowed.has(id));
+	const currentExisting = existing.filter((id) => allowed.has(id));
+	const normalizedCurrent = normalizeSupportingObservationIds([...currentExisting, ...incoming], allowedObservationIds);
+	if (!normalizedCurrent) return undefined;
+	return [...historicalExisting, ...normalizedCurrent];
+}
+
+export function renderReflectionsForReflectorPrompt(reflections: MemoryReflection[]): string {
+	return joinReflectionsOrEmpty(reflections);
+}
+
+export function applyReflectionProposals(
+	reflections: MemoryReflection[],
+	proposals: readonly ReflectionProposal[],
+	allowedObservationIds: readonly string[],
+	passContext: Pick<ReflectorPassContext, "minSupportingObservationIds">,
+): ApplyReflectionProposalsResult {
+	const next = [...reflections];
+	let accepted = 0;
+	let added = 0;
+	let merged = 0;
+	let promoted = 0;
+	let duplicates = 0;
+	let unsupported = 0;
+
+	for (const proposal of proposals) {
+		const content = normalizeReflectionProposalContent(proposal.content);
+		if (!content) {
+			unsupported++;
+			continue;
+		}
+		const supportingObservationIds = normalizeSupportingObservationIds(
+			proposal.supportingObservationIds,
+			allowedObservationIds,
+		);
+		if (!supportingObservationIds || supportingObservationIds.length < passContext.minSupportingObservationIds) {
+			unsupported++;
+			continue;
+		}
+
+		const existingIndex = next.findIndex((reflection) => reflectionContentKey(reflection) === content);
+		if (existingIndex >= 0) {
+			const existing = next[existingIndex];
+			if (typeof existing === "string") {
+				next[existingIndex] = {
+					id: hashId(content),
+					content,
+					supportingObservationIds,
+				};
+				accepted++;
+				promoted++;
+				continue;
+			}
+
+			const mergedSupport = mergeSupportingObservationIds(
+				existing.supportingObservationIds,
+				supportingObservationIds,
+				allowedObservationIds,
+			);
+			if (!mergedSupport) {
+				unsupported++;
+				continue;
+			}
+			const hasNewSupport = mergedSupport.length !== existing.supportingObservationIds.length;
+			if (existing.legacy === true) {
+				next[existingIndex] = {
+					id: existing.id,
+					content: existing.content,
+					supportingObservationIds: mergedSupport,
+				};
+				accepted++;
+				promoted++;
+				continue;
+			}
+			if (hasNewSupport) {
+				next[existingIndex] = {
+					...existing,
+					supportingObservationIds: mergedSupport,
+				};
+				accepted++;
+				merged++;
+			} else {
+				duplicates++;
+			}
+			continue;
+		}
+
+		next.push({
+			id: hashId(content),
+			content,
+			supportingObservationIds,
+		});
+		accepted++;
+		added++;
+	}
+
+	return { reflections: next, accepted, added, merged, promoted, duplicates, unsupported };
+}
+
+async function runReflectorPass(
 	args: LlmArgs,
-	reflections: Reflection[],
+	reflections: MemoryReflection[],
 	observations: ObservationRecord[],
-): Promise<Reflection[]> {
-	const existing = new Set(reflections.map((r) => r.trim()));
-	const added = new Set<string>();
+	passContext: ReflectorPassContext,
+): Promise<{ reflections: MemoryReflection[]; failed: boolean }> {
+	const allowedObservationIds = observations.map((o) => o.id);
+	let currentReflections = reflections;
 
 	const recordTool: AgentTool<typeof RecordReflectionsSchema> = {
 		name: "record_reflections",
 		label: "Record reflections",
 		description:
-			"Record a batch of new reflections crystallized from the observation pool. " +
-			"May be called multiple times. Stop calling when nothing more is stable enough to crystallize, " +
+			"Record a batch of reflections crystallized from the observation pool. " +
+			"May be called multiple times. Stop calling when nothing more is stable enough to crystallize for this pass, " +
 			"then emit a short plain-text confirmation.",
 		parameters: RecordReflectionsSchema,
 		execute: async (_id, params: RecordReflectionsArgs) => {
-			let accepted = 0;
-			let duplicates = 0;
-			for (const r of params.reflections) {
-				const content = truncateRecordContent(r.trim());
-				if (!content) continue;
-				if (existing.has(content) || added.has(content)) {
-					duplicates++;
-					continue;
-				}
-				added.add(content);
-				accepted++;
-			}
+			const result = applyReflectionProposals(
+				currentReflections,
+				params.reflections,
+				allowedObservationIds,
+				passContext,
+			);
+			currentReflections = result.reflections;
 			const parts: string[] = [];
-			parts.push(`Recorded ${accepted} new reflection${accepted === 1 ? "" : "s"}.`);
-			if (duplicates) parts.push(`${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped.`);
-			parts.push(`Total new this run: ${added.size}.`);
-			parts.push("Call record_reflections again if more should be crystallized; otherwise stop and emit a short plain-text confirmation.");
+			parts.push(`Accepted ${result.accepted} reflection proposal${result.accepted === 1 ? "" : "s"}.`);
+			if (result.added) parts.push(`${result.added} new.`);
+			if (result.merged) parts.push(`${result.merged} merged into existing reflections.`);
+			if (result.promoted) parts.push(`${result.promoted} promoted from legacy/no-provenance memory.`);
+			if (result.duplicates) parts.push(`${result.duplicates} duplicate/no-op proposal${result.duplicates === 1 ? "" : "s"} skipped.`);
+			if (result.unsupported) {
+				parts.push(
+					`${result.unsupported} unsupported proposal${result.unsupported === 1 ? "" : "s"} rejected for invalid supporting observation ids or this pass's minimum support requirement.`,
+				);
+			}
+			parts.push("Call record_reflections again if more should be crystallized for this pass; otherwise stop and emit a short plain-text confirmation.");
 			return {
 				content: [{ type: "text", text: parts.join(" ") }],
-				details: { accepted, duplicates, total: added.size },
+				details: result,
 			};
 		},
 	};
 
+	const passGuidance = buildReflectorPassGuidance(passContext.pass, passContext.maxPasses);
 	const userText = `CURRENT REFLECTIONS:
-${joinReflectionsOrEmpty(reflections)}
+${renderReflectionsForReflectorPrompt(reflections)}
 
 CURRENT OBSERVATIONS:
 ${joinObservationsOrEmpty(observations)}
 
-Crystallize new long-lived reflections from the observation pool. Call record_reflections with batches of new reflections. You may call the tool multiple times as you reason through the pool. Do not restate reflections already in the current reflections list. When done, stop calling the tool and emit a short plain-text confirmation.`;
+REFLECTOR PASS GUIDANCE:
+${passGuidance}
+
+Crystallize long-lived reflections from the full observation pool for this pass. Call record_reflections with batches of reflection proposals, each with the exact supporting observation ids. You may call the tool multiple times as you reason through the pool. To strengthen or promote an existing reflection, repeat the exact existing reflection content with valid supporting observation ids. Do not lightly reword existing reflections. When done, stop calling the tool and emit a short plain-text confirmation.`;
 
 	const prompts: Message[] = [
 		{
@@ -119,16 +384,33 @@ Crystallize new long-lived reflections from the observation pool. Call record_re
 	};
 
 	try {
-		const stream = agentLoop(prompts, context, config, args.signal);
+		const loop = args.agentLoop ?? agentLoop;
+		const stream = loop(prompts, context, config, args.signal);
 		for await (const _event of stream) {
-			// Drain events; the tool's execute already collects reflections.
+			// Drain events; the tool's execute already updates reflections.
 		}
 		await stream.result();
 	} catch {
-		// Salvage any reflections accepted before the error; downstream pruner still runs.
+		return { reflections: currentReflections, failed: true };
+	}
+
+	return { reflections: currentReflections, failed: false };
+}
+
+export async function runReflector(
+	args: LlmArgs,
+	reflections: MemoryReflection[],
+	observations: ObservationRecord[],
+): Promise<MemoryReflection[]> {
+	let currentReflections = reflections;
+
+	for (let pass = 1; pass <= REFLECTOR_MAX_PASSES; pass++) {
+		const result = await runReflectorPass(args, currentReflections, observations, reflectorPassContext(pass));
+		currentReflections = result.reflections;
+		if (result.failed) break;
 	}
 
-	return Array.from(added);
+	return currentReflections;
 }
 
 export interface PrunerResult {
@@ -161,6 +443,7 @@ interface PrunerPassContext {
 	deltaTokens: number;
 	pass: number;
 	maxPasses: number;
+	coverageTags: ReadonlyMap<string, ObservationCoverageTag>;
 }
 
 interface PrunerPassResult {
@@ -171,7 +454,7 @@ interface PrunerPassResult {
 
 async function runPrunerPass(
 	args: LlmArgs,
-	reflections: Reflection[],
+	reflections: MemoryReflection[],
 	observations: ObservationRecord[],
 	passContext: PrunerPassContext,
 ): Promise<PrunerPassResult> {
@@ -226,7 +509,7 @@ async function runPrunerPass(
 ${joinReflectionsOrEmpty(reflections)}
 
 CURRENT OBSERVATIONS:
-${joinObservationsOrEmpty(observations)}
+${renderObservationsForPrunerPrompt(observations, passContext.coverageTags)}
 
 ${pressureLine}
 
@@ -260,7 +543,8 @@ Decide which observations to remove from the kept set. Call drop_observations wi
 	};
 
 	try {
-		const stream = agentLoop(prompts, context, config, args.signal);
+		const loop = args.agentLoop ?? agentLoop;
+		const stream = loop(prompts, context, config, args.signal);
 		for await (const _event of stream) {
 			// Drain events; the tool's execute already records drops.
 		}
@@ -275,7 +559,7 @@ Decide which observations to remove from the kept set. Call drop_observations wi
 
 export async function runPruner(
 	args: LlmArgs,
-	reflections: Reflection[],
+	reflections: MemoryReflection[],
 	observations: ObservationRecord[],
 	budgetTokens: number,
 ): Promise<PrunerResult> {
@@ -285,6 +569,7 @@ export async function runPruner(
 
 	const target = Math.max(1, Math.floor(budgetTokens * PRUNER_TARGET_RATIO));
 	let pool = observations;
+	const coverageTags = deriveObservationCoverageTags(reflections, observations);
 	const allDropped: string[] = [];
 	let fellBack = false;
 
@@ -299,6 +584,7 @@ export async function runPruner(
 			deltaTokens,
 			pass,
 			maxPasses: PRUNER_MAX_PASSES,
+			coverageTags,
 		});
 
 		if (result.fellBack) {
@@ -314,13 +600,13 @@ export async function runPruner(
 	return { observations: pool, droppedIds: allDropped, fellBack };
 }
 
-export function renderSummary(reflections: Reflection[], observations: ObservationRecord[]): string {
+export function renderSummary(reflections: MemoryReflection[], observations: ObservationRecord[]): string {
 	if (reflections.length === 0 && observations.length === 0) return "";
 
 	const parts: string[] = [CONTEXT_USAGE_INSTRUCTIONS];
 
 	if (reflections.length > 0) {
-		parts.push(`## Reflections\n${reflections.join("\n")}`);
+		parts.push(`## Reflections\n${reflections.map(reflectionToPromptLine).join("\n")}`);
 	}
 	if (observations.length > 0) {
 		const body = observationsToPromptLines(observations).join("\n");

package/src/config.ts

@@ -6,6 +6,7 @@ export interface Config {
 	observationThresholdTokens: number;
 	compactionThresholdTokens: number;
 	reflectionThresholdTokens: number;
+	passive: boolean;
 	compactionModel?: { provider: string; id: string };
 }
 
@@ -13,22 +14,39 @@ export const DEFAULTS: Config = {
 	observationThresholdTokens: 1_000,
 	compactionThresholdTokens: 50_000,
 	reflectionThresholdTokens: 30_000,
+	passive: false,
 };
 
 const SETTINGS_KEY = "observational-memory";
+const PASSIVE_ENV = "PI_OBSERVATIONAL_MEMORY_PASSIVE";
+
+function normalizeSettingsConfig(value: Partial<Config>): Partial<Config> {
+	const normalized = { ...value };
+	if ("passive" in normalized && typeof normalized.passive !== "boolean") delete normalized.passive;
+	return normalized;
+}
+
+export function readEnvConfig(env: NodeJS.ProcessEnv = process.env): Partial<Config> {
+	const rawPassive = env[PASSIVE_ENV];
+	if (rawPassive === undefined) return {};
+	const passive = rawPassive.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(passive)) return { passive: true };
+	if (["0", "false", "no", "off"].includes(passive)) return { passive: false };
+	return {};
+}
 
 function readNamespacedConfig(path: string): Partial<Config> {
 	if (!existsSync(path)) return {};
 	try {
 		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
 		const nested = raw[SETTINGS_KEY];
-		return nested && typeof nested === "object" ? (nested as Partial<Config>) : {};
+		return nested && typeof nested === "object" ? normalizeSettingsConfig(nested as Partial<Config>) : {};
 	} catch {
 		return {};
 	}
 }
 
-export function loadConfig(cwd: string): Config {
+export function loadConfig(cwd: string, env: NodeJS.ProcessEnv = process.env): Config {
 	const globalPath = join(getAgentDir(), "settings.json");
 	const projectPath = join(cwd, ".pi", "settings.json");
 
@@ -36,5 +54,6 @@ export function loadConfig(cwd: string): Config {
 		...DEFAULTS,
 		...readNamespacedConfig(globalPath),
 		...readNamespacedConfig(projectPath),
+		...readEnvConfig(env),
 	};
 }