pi-observational-memory 2.4.1 → 2.4.3

package/src/observer.ts

@@ -1,8 +1,9 @@
 import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@mariozechner/pi-agent-core";
-import type { Message, Model } from "@mariozechner/pi-ai";
+import type { Message, Model, ModelThinkingLevel } from "@mariozechner/pi-ai";
 import { Type } from "@mariozechner/pi-ai";
-import type { Static } from "@sinclair/typebox";
+import type { Static } from "typebox";
 import { hashId } from "./ids.js";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";
 import { nowTimestamp, truncateRecordContent } from "./serialize.js";
 import type { ObservationRecord, Relevance } from "./types.js";
@@ -16,6 +17,9 @@ interface RunObserverArgs {
 	chunk: string;
 	allowedSourceEntryIds: string[];
 	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	maxTurns?: number;
+	thinkingLevel?: ModelThinkingLevel;
 }
 
 const RelevanceSchema = Type.Union([
@@ -25,11 +29,13 @@ const RelevanceSchema = Type.Union([
 	Type.Literal("critical"),
 ]);
 
+export const OBSERVATION_TIMESTAMP_PATTERN = "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}$";
+
 const RecordObservationsSchema = Type.Object({
 	observations: Type.Array(
 		Type.Object({
 			timestamp: Type.String({
-				pattern: "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$",
+				pattern: OBSERVATION_TIMESTAMP_PATTERN,
 				description: "Observation time in local 'YYYY-MM-DD HH:MM' format.",
 			}),
 			content: Type.String({
@@ -156,17 +162,29 @@ ${conversation}`;
 	};
 
 	const reasoning = (model as { reasoning?: unknown }).reasoning;
+	const thinkingLevel = args.thinkingLevel ?? "low";
+	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
+	let turnCount = 0;
 	const config: AgentLoopConfig = {
 		model,
 		apiKey,
 		headers,
-		maxTokens: 4096,
+		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
-		...(reasoning ? { reasoning: "high" as const } : {}),
+		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+		...(effectiveMaxTurns !== undefined
+			? {
+				shouldStopAfterTurn: () => {
+					turnCount++;
+					return turnCount >= effectiveMaxTurns;
+				},
+			}
+			: {}),
 	};
 
-	const stream = agentLoop(prompts, context, config, signal);
+	const loop = args.agentLoop ?? agentLoop;
+	const stream = loop(prompts, context, config, signal);
 	for await (const _event of stream) {
 		// Drain events; the tool's execute already collects records.
 	}

package/src/progress.ts

@@ -0,0 +1,155 @@
+import type { AgentEvent } from "@mariozechner/pi-agent-core";
+
+export type CompactionPhase = "observer" | "reflector" | "pruner";
+
+export interface ThemeLike {
+	fg: (color: string, text: string) => string;
+}
+
+const ALL_PHASES: CompactionPhase[] = ["observer", "reflector", "pruner"];
+
+export class CompactionProgressTracker {
+	private phase: CompactionPhase | undefined;
+	private pass = 0;
+	private maxPasses = 0;
+	private toolCallCount = 0;
+	private turnCount = 0;
+	// Starting counts before compaction tools run
+	private startingReflections = 0;
+	private startingObservations = 0;
+	// Accumulated deltas across all passes within a phase
+	private reflectionsAdded = 0;
+	private reflectionsMerged = 0;
+	private observationsDropped = 0;
+	private completedPhases: CompactionPhase[] = [];
+
+	getPhase(): CompactionPhase | undefined {
+		return this.phase;
+	}
+
+	getPass(): number {
+		return this.pass;
+	}
+
+	getMaxPasses(): number {
+		return this.maxPasses;
+	}
+
+	getToolCallCount(): number {
+		return this.toolCallCount;
+	}
+
+	getTurnCount(): number {
+		return this.turnCount;
+	}
+
+	setPhase(phase: CompactionPhase, pass: number, maxPasses: number): void {
+		if (this.phase && this.phase !== phase && !this.completedPhases.includes(this.phase)) {
+			this.completedPhases.push(this.phase);
+		}
+		// Reset deltas when transitioning to a different phase
+		if (this.phase !== phase) {
+			this.reflectionsAdded = 0;
+			this.reflectionsMerged = 0;
+			this.observationsDropped = 0;
+		}
+		this.phase = phase;
+		this.pass = pass;
+		this.maxPasses = maxPasses;
+		this.toolCallCount = 0;
+		this.turnCount = 0;
+	}
+
+	setStartingCounts(reflections: number, observations: number): void {
+		this.startingReflections = reflections;
+		this.startingObservations = observations;
+	}
+
+	setCompletedPhases(phases: CompactionPhase[]): void {
+		this.completedPhases = phases;
+	}
+
+	onEvent(event: AgentEvent): void {
+		if (!this.phase) return;
+		switch (event.type) {
+			case "tool_execution_start":
+				this.toolCallCount++;
+				break;
+			case "tool_execution_end": {
+				if (event.isError) break;
+				const details = (event.result as { details?: Record<string, unknown> } | undefined)?.details;
+				if (!details) break;
+				if (event.toolName === "record_reflections") {
+					this.reflectionsAdded += (details.added as number) ?? 0;
+					this.reflectionsMerged += (details.merged as number) ?? 0;
+				} else if (event.toolName === "drop_observations") {
+					this.observationsDropped += Array.isArray(details.dropped) ? details.dropped.length : 0;
+				}
+				break;
+			}
+			case "turn_start":
+				this.turnCount++;
+				break;
+		}
+	}
+
+	clear(): void {
+		this.phase = undefined;
+		this.pass = 0;
+		this.maxPasses = 0;
+		this.toolCallCount = 0;
+		this.turnCount = 0;
+		this.startingReflections = 0;
+		this.startingObservations = 0;
+		this.reflectionsAdded = 0;
+		this.reflectionsMerged = 0;
+		this.observationsDropped = 0;
+		this.completedPhases = [];
+	}
+
+	formatWidget(theme: ThemeLike): string {
+		if (!this.phase) return "";
+
+		const parts: string[] = [];
+
+		// Pipeline overview: show all phases with completion state
+		const phaseLabels = ALL_PHASES.map((p) => {
+			if (p === this.phase) {
+				return theme.fg("accent", p.charAt(0).toUpperCase() + p.slice(1));
+			}
+			if (this.completedPhases.includes(p)) {
+				return theme.fg("success", `✓${p.charAt(0).toUpperCase()}`);
+			}
+			return theme.fg("dim", p.charAt(0).toUpperCase());
+		});
+		parts.push(phaseLabels.join(theme.fg("dim", " → ")));
+
+		// Pass info (only for multi-pass phases)
+		if (this.maxPasses > 1) {
+			parts.push(theme.fg("muted", `pass ${this.pass}/${this.maxPasses}`));
+		}
+
+		// Tool calls
+		const tcLabel = this.toolCallCount === 1 ? "tool call" : "tool calls";
+		parts.push(theme.fg("muted", `${this.toolCallCount} ${tcLabel}`));
+
+		// Delta counters: R total(+accumulated), M total(+accumulated), O remaining(-accumulated)
+		const deltas: string[] = [];
+		if (this.reflectionsAdded > 0) {
+			const total = this.startingReflections + this.reflectionsAdded;
+			deltas.push(`R ${total}(+${this.reflectionsAdded})`);
+		}
+		if (this.reflectionsMerged > 0) {
+			deltas.push(`M ${this.reflectionsMerged}`);
+		}
+		if (this.observationsDropped > 0) {
+			const remaining = this.startingObservations - this.observationsDropped;
+			deltas.push(`O ${remaining}(-${this.observationsDropped})`);
+		}
+		if (deltas.length > 0) {
+			parts.push(theme.fg("accent", deltas.join(" ")));
+		}
+
+		return parts.join(theme.fg("dim", " · "));
+	}
+}

package/src/prompts.ts

@@ -150,7 +150,7 @@ You receive:
 
 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 proposals. Each proposal must include the reflection content and the exact supporting observation ids.
+2. Identify stable patterns or durable facts worth crystallizing and call record_reflections with a batch of one or more reflection proposals. Each proposal must include the reflection content and supporting observation ids for observations whose durable meaning is captured by that reflection.
 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.
 
@@ -160,9 +160,10 @@ What to emit:
 - 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.
+- For every reflection proposal, include supportingObservationIds for current observations whose durable meaning is captured by the reflection and can be treated as redundant active-memory detail. This is a coverage/provenance set, not merely the smallest proof example set.
+- Include additional current observation ids when the reflection preserves their durable meaning with equivalent fidelity. Do not include observations whose unique exact detail, current task state, user correction, user constraint, or concrete completion is not captured by 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.
+- Crystallize preferentially from "high" and "critical" observations, then old "medium" observations whose durable meaning can be covered; ignore "low" unless a pattern across many "low" observations is itself significant.
 - Focus on:
   - User identity, role, preferences, constraints.
   - Project goals, architectural decisions, key technical decisions and their rationale.
@@ -206,10 +207,12 @@ You receive:
 - 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 tags are pruning signals derived from current provenance-backed reflection support ids. They are strong evidence, not blind commands:
 - [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.
+- [coverage: cited] means 1-3 current provenance-backed reflections cite this observation. Once it is old, it is a strong pruning candidate for low/medium observations when the reflection preserves equivalent meaning. Old high observations can also be dropped when the reflection captures the same fact, unless they carry current task state or exact details not captured with equivalent fidelity.
+- [coverage: reinforced] means 4 or more current provenance-backed reflections cite this observation. Once it is old, it is a presumptive drop candidate because durable meaning is likely represented. Still preserve it if it carries current/recent task state, exact errors, file paths, commands, identifiers, user assertions, constraints, corrections, concrete completions, or nuance not captured with equivalent fidelity.
+
+Active-memory framing. Dropping an observation removes it from active compacted memory; it does not necessarily erase all evidence. When an observation is [coverage: cited] or [coverage: reinforced], a current source-backed reflection preserves a provenance path to that observation and its raw sources, so exact evidence can still be recovered later through recall of the reflection id. Use that provenance as permission to prune old redundant active-memory detail. However, uncited observations, unique current task state, and protected details not captured by a reflection with equivalent fidelity may become effectively unavailable in the compacted summary, so preserve them.
 
 How you work:
 1. Read reflections and the observation pool.
@@ -220,7 +223,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 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.
+- Signal-captured: observations tagged [coverage: reinforced] or [coverage: cited] whose durable meaning is captured by a reflection now in the reflections list. Old reinforced observations should usually be dropped unless they uniquely carry protected details. Old cited low/medium observations are strong drop candidates. Old cited high observations may be dropped when the reflection captures the same fact, but keep them when they contain current/recent task state, exact errors, file paths, commands, identifiers, user assertions, constraints, corrections, concrete completions, 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.
@@ -232,8 +235,8 @@ Age-gradient rule. Recent observations carry working context the assistant still
 
 Relevance guidance:
 - "low": drop freely once reviewed. Why: these were marked low because they add little signal; keeping them crowds out more useful records.
-- "medium": drop when redundant with reflections or other observations, or when the task context has moved on.
-- "high": drop only when clearly superseded or already captured by a reflection.
+- "medium": drop when redundant with reflections or other observations, especially when [coverage: cited] or [coverage: reinforced], or when the task context has moved on.
+- "high": drop when clearly superseded or already captured by a reflection; for old [coverage: cited] or [coverage: reinforced] high observations, require only that the reflection captures the same durable fact and no protected exact detail is unique to the observation.
 - "critical": NEVER drop. These encode user identity, explicit corrections, and concrete completions. Why this matters: dropping a critical item causes the assistant to repeat finished work, contradict an explicit correction, or misrepresent who the user is. No amount of budget pressure justifies this.
 
 User assertions and concrete completions are never droppable, even at non-critical relevance. If the relevance was mis-labeled but the content is load-bearing (an assertion about the user or a marker that work is done), treat the content as authoritative and skip the drop.
@@ -254,40 +257,38 @@ 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, 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.
+When in doubt, prefer dropping reinforced observations first, then cited observations, before uncited observations. Coverage tags are strong signals, not blind commands: reflections protect durable facts only when they preserve equivalent meaning. The only things you must preserve unconditionally are critical observations, user assertions, and concrete completions.
 
 What you CANNOT do:
 - You cannot merge observations. If two overlap, drop the weaker one.
 - You cannot rewrite or edit observations. The kept set preserves content, timestamp, and relevance exactly as they were.
 - You cannot add new observations.
 
-It is valid to end a pass with zero drops if the pool genuinely has nothing more to cut — a follow-up pass will be skipped when a run returns zero drops. Do not force drops you don't believe in.
+It is valid to end a pass with zero drops if the pool genuinely has nothing more to cut — a follow-up pass will be skipped when a run returns zero drops. On late pressure passes, first re-check old [coverage: reinforced] and [coverage: cited] observations as active-memory redundancies before deciding there are no sound drops. Do not force drops you don't believe in.
 
-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.`;
+Remember: pruning is active-memory management, not source deletion. A drop that looks reasonable at "low" still becomes a mistake if the content was a user correction with a mis-labeled relevance and no reflection captures it with equivalent fidelity. Read before you cut.`;
 
-type ReflectorPassTier = 1 | 2 | 3;
+type ReflectorPassTier = 1 | 2;
 
 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.`,
+	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 whose durable meaning is captured by the reflection. Do not create one-off event summaries; leave important single-observation facts, safety review, and coverage strengthening for the final reflector pass. If an existing reflection already captures the pattern, repeat the exact same content when adding support ids materially improves active-memory coverage.`,
+	2: `Pass strategy — final atomic durable facts, safety review, and coverage strengthening. 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, important technical context, and other load-bearing facts future agents must not forget. Review high and critical observations against current reflections, including reflections created in pass 1, and catch durable information still missing. Strengthen existing or newly-created reflections by repeating exact reflection content with additional supportingObservationIds for high, critical, and old medium observations whose durable meaning is already captured by that reflection. Do not duplicate earlier reflections; repeat exact existing content only to add missing support or promote no-provenance legacy memory. Create new reflections only when durable meaning is still missing. Do not create low-quality reflections just for coverage, and do not attach observations whose unique exact detail or current task state is not captured with equivalent fidelity.`,
 };
 
 export function buildReflectorPassGuidance(pass: number, maxPasses: number): string {
-	const tier = (Math.min(3, Math.max(1, pass)) as ReflectorPassTier);
+	const tier = (Math.min(2, Math.max(1, pass)) as ReflectorPassTier);
 	return `Pass ${pass} of up to ${maxPasses}. ${REFLECTOR_PASS_STRATEGIES[tier]}`;
 }
 
-type PrunerPassTier = 1 | 2 | 3;
+type PrunerPassTier = 1 | 2;
 
 const PRUNER_PASS_STRATEGIES: Record<PrunerPassTier, string> = {
-	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.`,
+	1: `Pass strategy — clear-cut source-backed drops only. Prefer old low-value [coverage: reinforced] observations, then old low/medium [coverage: cited] 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 unless the drop is an exact duplicate or direct supersession. Because there are only two pruning passes, do not defer obvious source-backed drops unnecessarily.`,
+	2: `Pass strategy — final topic compression, aggressive age compression, and budget-pressure rescue. This is the last pruning pass: make the strongest sound source-backed cuts available before stopping. First compress topics: drop "low" observations covered by recent "medium" or "high" observations, older [coverage: cited] "medium" observations whose substance is now covered by a reflection, and repeated tool-call sequences where one observation captures the learning. Then apply aggressive age compression: in the older half of the pool, drop non-outcome-bearing "low" and "medium" observations, strongly preferring [coverage: reinforced] and [coverage: cited] over [coverage: uncited]. Keep the most recent ~30% at higher detail unless an observation is clearly redundant and source-backed. Under budget pressure, treat old [coverage: reinforced] observations as active-memory redundancies by default when current source-backed reflections preserve their durable meaning. Drop reinforced low/medium/high observations unless they uniquely carry current task state or protected exact detail not captured with equivalent fidelity. Drop old [coverage: cited] high observations only when a reflection captures the same durable fact and the observation has no unique protected exact detail. Prefer source-backed reinforced/cited drops over any uncited drop. Do not drop critical observations, user assertions, concrete completions, explicit user corrections or constraints, current task state, unique exact errors/paths/commands/ids, dated events, or decision rationale unless an existing reflection preserves the same information with equivalent fidelity. Do not fabricate drops solely to hit the target.`,
 };
 
 export function buildPrunerPassGuidance(pass: number, maxPasses: number): string {
-	const tier = (Math.min(3, Math.max(1, pass)) as PrunerPassTier);
+	const tier = (Math.min(2, Math.max(1, pass)) as PrunerPassTier);
 	return `Pass ${pass} of up to ${maxPasses}. ${PRUNER_PASS_STRATEGIES[tier]}`;
 }