pi-observational-memory-extension 0.1.0

package/extensions/index.ts

@@ -0,0 +1,1400 @@
+import { complete } from "@earendil-works/pi-ai";
+import {
+  CONFIG_DIR_NAME,
+  convertToLlm,
+  serializeConversation,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const EXTENSION_ID = "pi-observational-memory";
+const STATE_VERSION = 1;
+const DEFAULT_OBSERVATION_MODEL = "google/gemini-2.5-flash";
+const DEFAULT_REFLECTION_MODEL = "google/gemini-2.5-flash";
+const OBSERVATION_THRESHOLD = 30_000;
+const REFLECTION_THRESHOLD = 40_000;
+const OBSERVER_MAX_BATCH_TOKENS = 10_000;
+const BUFFER_TOKENS_RATIO = 0.2;
+const BUFFER_ACTIVATION_RATIO = 0.8;
+const DEFAULT_BLOCK_AFTER_MULTIPLIER = 1.2;
+const TOOL_RESULT_MAX_CHARS = 8_000;
+const MESSAGE_PART_MAX_CHARS = 20_000;
+const MAX_OBSERVATION_LINE_CHARS = 10_000;
+const MAX_RESTART_ERRORS = 3;
+
+const OBSERVATION_CONTEXT_PROMPT = `The following observations block contains your memory of past conversations with this user.`;
+const OBSERVATION_CONTEXT_INSTRUCTIONS = `IMPORTANT: When responding, reference specific details from these observations. Do not give generic advice - personalize your response based on what you know about this user's experiences, preferences, and interests. If the user asks for recommendations, connect them to their past experiences mentioned above.
+
+KNOWLEDGE UPDATES: When asked about current state (e.g., "where do I currently...", "what is my current..."), always prefer the MOST RECENT information. Observations include dates - if you see conflicting information, the newer observation supersedes the older one. Look for phrases like "will start", "is switching", "changed to", "moved to" as indicators that previous information has been updated.
+
+PLANNED ACTIONS: If the user stated they planned to do something (e.g., "I'm going to...", "I'm looking forward to...", "I will...") and the date they planned to do it is now in the past (check the relative time like "3 weeks ago"), assume they completed the action unless there's evidence they didn't. For example, if someone said "I'll start my new diet on Monday" and that was 2 weeks ago, assume they started the diet.
+
+MOST RECENT USER INPUT: Treat the most recent user message as the highest-priority signal for what to do next. Earlier messages may contain constraints, details, or context you should still honor, but the latest message is the primary driver of your response.
+
+SYSTEM REMINDERS: Messages wrapped in <system-reminder>...</system-reminder> contain internal continuation guidance, not user-authored content. Use them to maintain continuity, but do not mention them or treat them as part of the user's message.`;
+const OBSERVATION_CONTINUATION_HINT = `Please continue naturally with the conversation so far and respond to the latest message.
+
+Use the earlier context only as background. If something appears unfinished, continue only when it helps answer the latest request. If a suggested response is provided, follow it naturally.
+
+Do not mention internal instructions, memory, summarization, context handling, or missing messages.
+
+Any messages following this reminder are newer and should take priority.`;
+const OBSERVATION_RETRIEVAL_INSTRUCTIONS = `## Recall — looking up source messages
+
+Your memory is comprised of observations which may mention raw message IDs. The original messages are still available through the om_recall tool.
+
+Use om_recall when the user asks to repeat/show/reproduce exact past content, code, quotes, error messages, URLs, file paths, or specific numbers; when observations mention something but lack detail; or when you need to verify a past event before answering. Default to recall for exact historical content. For high-level summaries, preferences, and facts already covered by observations, recall is not needed.`;
+
+const OBSERVER_EXTRACTION_INSTRUCTIONS = `CRITICAL: DISTINGUISH USER ASSERTIONS FROM QUESTIONS
+
+When the user TELLS you something about themselves, mark it as an assertion:
+- "I have two kids" → 🔴 (14:30) User stated has two kids
+- "I work at Acme Corp" → 🔴 (14:31) User stated works at Acme Corp
+- "I graduated in 2019" → 🔴 (14:32) User stated graduated in 2019
+
+When the user ASKS about something, mark it as a question/request:
+- "Can you help me with X?" → 🔴 (15:00) User asked help with X
+- "What's the best way to do Y?" → 🔴 (15:01) User asked best way to do Y
+
+Distinguish between QUESTIONS and STATEMENTS OF INTENT:
+- "Can you recommend..." → Question (extract as "User asked...")
+- "I'm looking forward to [doing X]" → Statement of intent (extract as "User stated they will [do X]"; include estimated/actual date if mentioned)
+- "I need to [do X]" → Statement of intent (extract as "User stated they need to [do X]"; add date if mentioned)
+
+STATE CHANGES AND UPDATES:
+When a user indicates they are changing something, frame it as a state change that supersedes previous information:
+- "I'm going to start doing X instead of Y" → "User will start doing X (changing from Y)"
+- "I'm switching from A to B" → "User is switching from A to B"
+- "I moved my stuff to the new place" → "User moved their stuff to the new place (no longer at previous location)"
+
+If the new state contradicts or updates previous information, make that explicit:
+- BAD: "User plans to use the new method"
+- GOOD: "User will use the new method (replacing the old approach)"
+
+USER ASSERTIONS ARE AUTHORITATIVE. The user is the source of truth about their own life. If a user previously stated something and later asks a question about the same topic, the assertion is the answer - the question doesn't invalidate what they already told you.
+
+TEMPORAL ANCHORING:
+Each observation has TWO potential timestamps:
+1. BEGINNING: The time the statement was made (from the message timestamp) - ALWAYS include this
+2. END: The time being REFERENCED, if different from when it was said - ONLY when there's a relative time reference and you can provide an actual date.
+
+FORMAT:
+- With time reference: (TIME) [observation]. (meaning/estimated DATE)
+- Without time reference: (TIME) [observation].
+ALWAYS put referenced dates at the END in parentheses.
+If an observation contains MULTIPLE events, split them into SEPARATE observation lines. Each split observation MUST have its own date at the end when applicable.
+
+PRESERVE UNUSUAL PHRASING:
+When the user uses unexpected or non-standard terminology, quote their exact words.
+
+USE PRECISE ACTION VERBS:
+Replace vague verbs like "getting", "got", "have" with specific action verbs that clarify the action. Prefer the assistant's precise clarification if it confirmed the user's meaning.
+
+PRESERVING DETAILS IN ASSISTANT-GENERATED CONTENT:
+Preserve distinguishing details in recommendation lists, names/handles/identifiers, creative content structure, technical/numerical results, quantities/counts, and user roles at events. Always preserve specific values, counts, identifiers, units, file paths, URLs, code snippets, and formatted text that may need to be reproduced.
+
+CONVERSATION CONTEXT:
+Capture what the user is working on, previous topics/outcomes, what the user understands or needs clarified, specific requirements/constraints, assistant explanations and detailed answers, relevant code snippets, user preferences, iteratively edited text, named entities and their identifying attributes, and any important sequences/data.
+
+USER MESSAGE CAPTURE:
+Short and medium user messages should be captured nearly verbatim in your own words. For very long user messages, summarize but quote key phrases that carry intent.
+
+AVOIDING REPETITIVE OBSERVATIONS:
+Do NOT repeat the same observation across multiple turns if there is no new information. Group repeated similar actions and tool calls under one parent observation with sub-bullets for new results. Observe what tools were called, why, and what was learned; do not list tools mechanically.
+
+ACTIONABLE INSIGHTS:
+Capture what worked, what needs follow-up, stated goals or next steps, and whether any non-requested next steps are waiting for user approval.
+
+COMPLETION TRACKING:
+Use ✅ for concrete task finished, question answered, issue resolved, goal achieved, or subtask completed. Completion observations tell the assistant what should not be repeated unless new information changes it. Prefer concrete resolved outcomes over vague progress summaries.`;
+
+function buildObserverOutputFormat(): string {
+  return `Use priority levels:
+- 🔴 High: explicit user facts, preferences, unresolved goals, critical context
+- 🟡 Medium: project details, learned information, tool results
+- 🟢 Low: minor details, uncertain observations
+- ✅ Completed: concrete task finished, question answered, issue resolved, goal achieved, or subtask completed
+
+Group related observations by indenting:
+* 🔴 (14:33) Agent debugging auth issue
+  * -> ran git status, found 3 modified files
+  * -> viewed auth.ts:45-60, found missing null check
+  * -> applied fix, tests now pass
+  * ✅ Tests passing, auth issue resolved
+
+Group observations by date, then list each with 24-hour time.
+
+<observations>
+Date: Dec 4, 2025
+* 🔴 (14:30) User prefers direct answers
+* 🔴 (14:31) Working on feature X
+* 🟡 (14:32) User might prefer dark mode
+
+Date: Dec 5, 2025
+* 🔴 (09:15) Continued work on feature X
+</observations>
+
+<current-task>
+State the current task(s) explicitly. Include primary current work and secondary pending tasks. Mark tasks as "waiting for user" where appropriate. If the agent started doing something without user approval, note that it's off-task.
+</current-task>
+
+<suggested-response>
+Hint for the agent's immediate next message. Examples:
+- "I've updated the navigation model. Let me walk you through the changes..."
+- "The assistant should wait for the user to respond before continuing."
+- Call the read tool on src/example.ts to continue debugging.
+</suggested-response>`;
+}
+
+const OBSERVER_GUIDELINES = `- Be specific enough for the assistant to act on
+- Good: "User prefers short, direct answers without lengthy explanations"
+- Bad: "User stated a preference" (too vague)
+- Add 1 to 5 observations per exchange
+- Use terse, dense language to save tokens
+- Do not add repetitive observations already observed
+- If the agent calls tools, observe what was called, why, and what was learned
+- Include file line numbers when useful
+- If the agent provides a detailed response, observe enough contents that it could be repeated
+- Start each observation with 🔴, 🟡, 🟢, or ✅
+- Capture the user's words closely; unresolved or critical user facts remain 🔴
+- Treat ✅ as a memory signal that tells the assistant what is finished
+- Observe WHAT the agent did and WHAT it means
+- If the user provides detailed messages or code snippets, observe all important details`;
+
+function buildObserverSystemPrompt(): string {
+  return `You are the memory consciousness of an AI assistant. Your observations will be the ONLY information the assistant has about past interactions with this user.
+
+Extract observations that will help the assistant remember:
+
+${OBSERVER_EXTRACTION_INSTRUCTIONS}
+
+=== OUTPUT FORMAT ===
+
+Your output MUST use XML tags to structure the response. This allows the system to properly parse and manage memory over time.
+
+${buildObserverOutputFormat()}
+
+=== GUIDELINES ===
+
+${OBSERVER_GUIDELINES}
+
+=== IMPORTANT: THREAD ATTRIBUTION ===
+
+Do NOT add thread identifiers, thread IDs, or <thread> tags to your observations. Thread attribution is handled externally by the system. Simply output your observations without thread-related markup.
+
+Remember: These observations are the assistant's ONLY memory. Make them count.
+
+User messages are extremely important. If the user asks a question or gives a new task, make it clear in <current-task> that this is the priority. If the assistant needs to respond to the user, indicate in <suggested-response> that it should pause for user reply before continuing other tasks.`;
+}
+
+function buildObserverTaskPrompt(existingObservations: string | undefined, opts: { priorCurrentTask?: string; priorSuggestedResponse?: string; wasTruncated?: boolean } = {}): string {
+  let prompt = "";
+  if (existingObservations?.trim()) {
+    prompt += `## Previous Observations\n\n${existingObservations}\n\n---\n\nDo not repeat these existing observations. Your new observations will be appended to the existing observations.\n\n`;
+  }
+  const metadata: string[] = [];
+  if (opts.priorCurrentTask) metadata.push(`- prior current-task: ${opts.priorCurrentTask}`);
+  if (opts.priorSuggestedResponse) metadata.push(`- prior suggested-response: ${opts.priorSuggestedResponse}`);
+  if (metadata.length) {
+    prompt += `## Prior Thread Metadata\n\n${metadata.join("\n")}\n\n`;
+    if (opts.wasTruncated) {
+      prompt += `Previous observations were truncated for context budget reasons. The main agent still has full memory context outside this observer window.\n`;
+    }
+    prompt += `Use prior current-task and suggested-response as continuity hints, then update them based on the new messages.\n\n---\n\n`;
+  }
+  prompt += `## Your Task\n\nExtract new observations from the message history above. Do not repeat observations that are already in previous observations. Add your new observations in the format specified in your instructions.`;
+  return prompt;
+}
+
+function buildReflectorSystemPrompt(): string {
+  return `You are the memory consciousness of an AI assistant. Your memory observation reflections will be the ONLY information the assistant has about past interactions with this user.
+
+The following instructions were given to another part of your psyche (the observer) to create memories.
+
+<observational-memory-instruction>
+${OBSERVER_EXTRACTION_INSTRUCTIONS}
+
+=== OUTPUT FORMAT ===
+
+${buildObserverOutputFormat()}
+
+=== GUIDELINES ===
+
+${OBSERVER_GUIDELINES}
+</observational-memory-instruction>
+
+You are another part of the same psyche, the observation reflector. Your reason for existing is to reflect on all the observations, re-organize and streamline them, and draw connections and conclusions between observations about what you've learned, seen, heard, and done.
+
+You are a greater and broader aspect of the psyche. Understand that other parts of your mind may get off track in details or side quests; identify the observed goal, whether we got off track, why, and how to get back on track.
+
+IMPORTANT: your reflections are THE ENTIRETY of the assistant's memory. Any information you do not add to your reflections will be immediately forgotten. Your reflections must assume the assistant knows nothing.
+
+When consolidating observations:
+- Preserve dates/times when present
+- Retain relevant timestamps
+- Combine related items where it makes sense
+- Preserve ✅ completion markers and concrete resolved outcomes
+- Condense older observations more aggressively, retain more detail for recent ones
+- Preserve user assertions over questions and newer state over superseded older state
+- Maintain thread attribution if it appears and matters; consolidate universal cross-thread facts
+
+=== OUTPUT FORMAT ===
+
+Your output MUST use XML tags:
+
+<observations>
+Put all consolidated observations here using date-grouped format with priority emojis. Group related observations with indentation.
+</observations>
+
+<current-task>
+State current task(s) explicitly: primary and secondary pending tasks. Mark waiting-for-user tasks.
+</current-task>
+
+<suggested-response>
+Hint for the agent's immediate next message.
+</suggested-response>
+
+User messages are extremely important. If the user asks a question or gives a new task, make it clear in <current-task> that this is the priority. If the assistant needs to respond, indicate in <suggested-response> that it should pause for user reply before continuing other tasks.`;
+}
+
+type CompressionLevel = 0 | 1 | 2 | 3 | 4;
+const COMPRESSION_GUIDANCE: Record<CompressionLevel, string> = {
+  0: "",
+  1: `\n## COMPRESSION REQUIRED\n\nYour previous reflection was the same size or larger than the original observations. Re-process with slightly more compression: condense older observations, retain recent detail, combine repeated tool calls into outcome summaries, preserve ✅ markers and important specifics. Aim for 8/10 detail.`,
+  2: `\n## AGGRESSIVE COMPRESSION REQUIRED\n\nYour previous reflection was still too large. Heavily condense older observations, retain recent important details, merge repeated files/modules, remove redundancy, preserve names/dates/decisions/errors/preferences/✅ outcomes. Aim for 6/10 detail.`,
+  3: `\n## CRITICAL COMPRESSION REQUIRED\n\nSummarize the oldest 50-70% into brief high-level paragraphs. Retain only key facts, decisions, outcomes, unresolved issues, user preferences, architectural choices, and recent details. Drop procedural tool details; keep final outcomes. Aim for 4/10 detail.`,
+  4: `\n## EXTREME COMPRESSION REQUIRED\n\nTool call observations are the biggest source of bloat. Collapse ALL tool sequences into outcome-only observations. Never preserve individual tool calls. Merge same-day groups, keep older topics to 1-2 observations, preserve ✅ outcomes/user preferences/decisions/unresolved issues. Aim for 2/10 detail.`,
+};
+
+function buildReflectorPrompt(observations: string, level: CompressionLevel, manualPrompt?: string): string {
+  let prompt = `## OBSERVATIONS TO REFLECT ON\n\n${observations}\n\n---\n\nPlease analyze these observations and produce a refined, condensed version that will become the assistant's entire memory going forward.`;
+  if (manualPrompt) prompt += `\n\n## SPECIFIC GUIDANCE\n\n${manualPrompt}`;
+  if (COMPRESSION_GUIDANCE[level]) prompt += `\n\n${COMPRESSION_GUIDANCE[level]}`;
+  return prompt;
+}
+
+type Status = "idle" | "observing" | "reflecting" | "buffering" | "failed" | "disabled";
+type OperationType = "observation" | "reflection" | "buffer" | "activation";
+
+type BufferedChunk = {
+  id: string;
+  startEntryId?: string;
+  endEntryId: string;
+  messageTokens: number;
+  observationTokens: number;
+  observations: string;
+  currentTask?: string;
+  suggestedResponse?: string;
+  createdAt: string;
+};
+
+type PiOMRecord = {
+  version: number;
+  enabled: boolean;
+  sessionId: string;
+  sessionFile?: string;
+  cwd: string;
+  scope: "session" | "project";
+  status: Status;
+  observations: string;
+  currentTask?: string;
+  suggestedResponse?: string;
+  lastObservedEntryId?: string;
+  pendingMessageTokens: number;
+  observationTokens: number;
+  thresholds: { observation: number; reflection: number; blockAfter: number; bufferTokens: number; bufferActivation: number };
+  buffered: { observations: BufferedChunk[]; reflection?: BufferedChunk };
+  operationLock?: { type: OperationType; startedAt: string };
+  lastOperation?: { type: OperationType; startedAt: string; endedAt?: string; inputTokens: number; outputTokens?: number; error?: string; model?: string; compressionLevel?: number };
+  lastError?: string;
+  lastProvider?: string;
+  lastModel?: string;
+  updatedAt: string;
+};
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+type AgentMessage = any;
+
+type ObserverResult = { observations: string; currentTask?: string; suggestedContinuation?: string; rawOutput: string; degenerate?: boolean };
+type ReflectorResult = { observations: string; currentTask?: string; suggestedContinuation?: string; rawOutput: string; degenerate?: boolean };
+
+type Runtime = {
+  state?: PiOMRecord;
+  statePath?: string;
+  debugDir?: string;
+  overlay?: OMOverlay;
+  overlayHandle?: { requestRender: () => void; close: () => void };
+  currentOperation?: AbortController;
+  statusTimer?: NodeJS.Timeout;
+  failureCount: number;
+};
+
+const runtime: Runtime = { failureCount: 0 };
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "om_recall",
+    label: "OM Recall",
+    description: "Recall raw Pi session messages hidden by Observational Memory pruning. Use for exact past content, code, quotes, file paths, URLs, or verification.",
+    promptSnippet: "Recall raw messages hidden by Observational Memory when exact past content is needed.",
+    promptGuidelines: ["Use om_recall when observations are insufficient for exact past content, code, quotes, file paths, URLs, or verification."],
+    parameters: Type.Object({
+      cursor: Type.Optional(Type.String({ description: "Entry id to start near. Defaults to last observed entry." })),
+      page: Type.Optional(Type.Number({ description: "Page offset from cursor. 0/current, positive forward, negative backward." })),
+      radius: Type.Optional(Type.Number({ description: "Messages around target entry. Default 6, max 20." })),
+      detail: Type.Optional(Type.Union([Type.Literal("low"), Type.Literal("high")], { description: "low truncates payloads; high returns more detail." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const state = await ensureState(ctx);
+      const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+      const cursor = params.cursor || state.lastObservedEntryId || branch.at(-1)?.id;
+      const detail = params.detail === "high" ? "high" : "low";
+      const radius = Math.min(Math.max(Number(params.radius ?? 6), 1), 20);
+      const page = Number(params.page ?? 0);
+      const idx = Math.max(0, branch.findIndex(e => e.id === cursor));
+      const center = Math.max(0, Math.min(branch.length - 1, idx + page * radius));
+      const start = Math.max(0, center - radius);
+      const end = Math.min(branch.length, center + radius + 1);
+      const entries = branch.slice(start, end).filter(isMessageLikeEntry);
+      const text = entries.map(e => serializeEntryForRecall(e, detail)).join("\n\n---\n\n");
+      return {
+        content: [{ type: "text", text: text || "No recallable messages near cursor." }],
+        details: { cursor, page, startEntryId: entries[0]?.id, endEntryId: entries.at(-1)?.id, hasPrevPage: start > 0, hasNextPage: end < branch.length },
+      };
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    await ensureState(ctx);
+    await refreshCounts(ctx);
+    updateStatus(ctx);
+    runtime.statusTimer = setInterval(() => updateStatus(ctx), 1000);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (runtime.statusTimer) clearInterval(runtime.statusTimer);
+    runtime.currentOperation?.abort();
+    if (runtime.state) await saveState(runtime.state);
+    ctx.ui.setStatus("om", undefined);
+    ctx.ui.setWidget("om", undefined);
+  });
+
+  pi.on("model_select", async (event, ctx) => {
+    const state = await ensureState(ctx);
+    const nextProvider = event.model?.provider;
+    const nextModel = event.model?.id;
+    const changed = state.lastProvider && state.lastModel && (state.lastProvider !== nextProvider || state.lastModel !== nextModel);
+    state.lastProvider = nextProvider;
+    state.lastModel = nextModel;
+    if (changed && state.buffered.observations.length > 0) {
+      await activateBuffered(ctx, "provider/model changed");
+    }
+    await saveState(state);
+    updateStatus(ctx);
+  });
+
+  pi.on("message_end", async (_event, ctx) => {
+    await safeBoundary(ctx, "message_end");
+  });
+
+  pi.on("tool_execution_end", async (_event, ctx) => {
+    await safeBoundary(ctx, "tool_execution_end");
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    await safeBoundary(ctx, "turn_end");
+  });
+
+  pi.on("context", async (event, ctx) => {
+    const state = await ensureState(ctx);
+    if (!state.enabled || !state.observations.trim()) return;
+    const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+    const unobserved = entriesAfter(branch, state.lastObservedEntryId)
+      .filter(isMessageLikeEntry)
+      .map(entryToAgentMessage)
+      .filter(Boolean) as AgentMessage[];
+    const omMessage = buildOMContextMessage(state);
+    const finalMessages = [omMessage, ...unobserved];
+    if (finalMessages.length <= 1) return { messages: [omMessage, ...event.messages.slice(-8)] };
+    return { messages: finalMessages };
+  });
+
+  pi.on("session_before_compact", async (event, ctx) => {
+    const state = await ensureState(ctx);
+    if (!state.enabled) return;
+    const startedAt = new Date().toISOString();
+    try {
+      ctx.ui.notify("OM compact: observing/reflection instead of legacy summary", "info");
+      await refreshCounts(ctx);
+      const prep = event.preparation as any;
+      const messages = [...(prep.messagesToSummarize ?? []), ...(prep.turnPrefixMessages ?? [])];
+      if (messages.length > 0) {
+        const text = serializeConversation(convertToLlm(messages));
+        const result = await runObserver(ctx, text, event.signal, { source: "compact", existingObservations: state.observations });
+        appendObservations(state, result, estimateTokens(text));
+      } else {
+        await observeNow(ctx, { force: true, signal: event.signal, reason: "compact" });
+      }
+      if (state.observationTokens >= state.thresholds.reflection) {
+        await reflectNow(ctx, { signal: event.signal, reason: "compact" });
+      }
+      const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+      const beforeKept = entriesBefore(branch, prep.firstKeptEntryId).at(-1);
+      if (beforeKept?.id) state.lastObservedEntryId = beforeKept.id;
+      state.pendingMessageTokens = Math.max(0, state.pendingMessageTokens - estimateMessagesTokens(messages));
+      state.status = "idle";
+      state.updatedAt = new Date().toISOString();
+      await saveState(state);
+      updateStatus(ctx);
+      const summary = buildCompactionSummary(state);
+      await writeDebug(ctx, "compact", { startedAt, summary, state });
+      return { compaction: { summary, firstKeptEntryId: prep.firstKeptEntryId, tokensBefore: prep.tokensBefore, details: { type: EXTENSION_ID, om: snapshotDetails(state) } } };
+    } catch (error) {
+      const message = errorMessage(error);
+      state.status = "failed";
+      state.lastError = `OM compact failed: ${message}`;
+      await saveState(state);
+      updateStatus(ctx);
+      ctx.ui.notify(state.lastError, "error");
+      throw error;
+    }
+  });
+
+  pi.registerCommand("om-status", {
+    description: "Show Observational Memory status.",
+    handler: async (_args, ctx) => {
+      const state = await ensureState(ctx);
+      await refreshCounts(ctx);
+      ctx.ui.notify(formatDetailedStatus(state), state.status === "failed" ? "error" : "info");
+      updateStatus(ctx);
+    },
+  });
+
+  pi.registerCommand("om-observe", {
+    description: "Force Observational Memory observation of pending raw context.",
+    handler: async (_args, ctx) => {
+      const state = await ensureState(ctx);
+      if (!state.enabled) throw new Error("Observational Memory is disabled");
+      await observeNow(ctx, { force: true, reason: "manual" });
+      updateStatus(ctx);
+      ctx.ui.notify("OM observation complete", "info");
+    },
+  });
+
+  pi.registerCommand("om-reflect", {
+    description: "Force Observational Memory reflection/compression.",
+    handler: async (args, ctx) => {
+      const state = await ensureState(ctx);
+      if (!state.enabled) throw new Error("Observational Memory is disabled");
+      await reflectNow(ctx, { reason: "manual", manualPrompt: args?.trim() || undefined });
+      updateStatus(ctx);
+      ctx.ui.notify("OM reflection complete", "info");
+    },
+  });
+
+  pi.registerCommand("om-memory", {
+    description: "Open Observational Memory overlay.",
+    handler: async (_args, ctx) => {
+      const state = await ensureState(ctx);
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify(formatMemoryText(state), "info");
+        return;
+      }
+      runtime.overlay = new OMOverlay(() => runtime.state, () => {
+        runtime.overlayHandle?.close();
+        runtime.overlayHandle = undefined;
+      });
+      await ctx.ui.custom((tui, theme, _kb, done) => {
+        runtime.overlay = new OMOverlay(() => runtime.state, () => done(undefined), () => tui.requestRender(), theme);
+        return runtime.overlay;
+      }, {
+        overlay: true,
+        overlayOptions: { width: "95%", maxHeight: "90%", anchor: "center", margin: 1 },
+        onHandle: (handle: any) => {
+          runtime.overlayHandle = handle;
+          handle.focus?.();
+        },
+      });
+    },
+  });
+
+  pi.registerCommand("om-enable", {
+    description: "Enable Observational Memory for this session.",
+    handler: async (_args, ctx) => {
+      const state = await ensureState(ctx);
+      state.enabled = true;
+      state.status = "idle";
+      await saveState(state);
+      updateStatus(ctx);
+      ctx.ui.notify("Observational Memory enabled", "info");
+    },
+  });
+
+  pi.registerCommand("om-disable", {
+    description: "Disable Observational Memory for this session.",
+    handler: async (_args, ctx) => {
+      const state = await ensureState(ctx);
+      state.enabled = false;
+      state.status = "disabled";
+      await saveState(state);
+      updateStatus(ctx);
+      ctx.ui.notify("Observational Memory disabled", "warning");
+    },
+  });
+
+  pi.registerCommand("om-compact", {
+    description: "Run Pi compaction; pi-observational-memory will replace the summary with OM.",
+    handler: async (args, ctx) => {
+      ctx.compact({
+        customInstructions: args || "Use Observational Memory compaction.",
+        onComplete: () => ctx.ui.notify("OM compaction completed", "info"),
+        onError: error => ctx.ui.notify(`OM compaction failed: ${error.message}`, "error"),
+      });
+    },
+  });
+}
+
+async function safeBoundary(ctx: any, boundary: string): Promise<void> {
+  const state = await ensureState(ctx);
+  if (!state.enabled || state.status === "failed") return;
+  await refreshCounts(ctx);
+  updateStatus(ctx);
+  if (runtime.currentOperation) return;
+  if (state.pendingMessageTokens >= state.thresholds.blockAfter) {
+    await observeNow(ctx, { force: true, reason: `${boundary}:block-after` });
+    if (state.observationTokens >= state.thresholds.reflection) await reflectNow(ctx, { reason: `${boundary}:threshold` });
+    return;
+  }
+  if (state.pendingMessageTokens >= effectiveObservationThreshold(state)) {
+    if (state.buffered.observations.length > 0) await activateBuffered(ctx, `${boundary}:threshold`);
+    await observeNow(ctx, { force: false, reason: `${boundary}:threshold` });
+    if (state.observationTokens >= state.thresholds.reflection) await reflectNow(ctx, { reason: `${boundary}:threshold` });
+    return;
+  }
+  if (shouldBuffer(state)) {
+    void bufferObservation(ctx, `${boundary}:buffer`).catch(async (error) => {
+      const s = await ensureState(ctx);
+      s.status = "failed";
+      s.lastError = `OM buffer failed: ${errorMessage(error)}`;
+      await saveState(s);
+      updateStatus(ctx);
+      ctx.ui.notify(s.lastError, "error");
+    });
+  }
+}
+
+async function ensureState(ctx: any): Promise<PiOMRecord> {
+  if (runtime.state && runtime.state.cwd === ctx.cwd && runtime.state.sessionFile === ctx.sessionManager.getSessionFile()) return runtime.state;
+  const sessionFile = ctx.sessionManager.getSessionFile?.();
+  const sessionId = ctx.sessionManager.getSessionId?.() || (sessionFile ? basename(sessionFile, ".jsonl") : "in-memory");
+  const dir = join(ctx.cwd, CONFIG_DIR_NAME, "om");
+  const debugDir = join(dir, "debug");
+  await mkdir(debugDir, { recursive: true });
+  const statePath = join(dir, `${sanitizeFileName(sessionId)}.json`);
+  runtime.statePath = statePath;
+  runtime.debugDir = debugDir;
+  let state: PiOMRecord | undefined;
+  if (existsSync(statePath)) {
+    try {
+      state = JSON.parse(await readFile(statePath, "utf8")) as PiOMRecord;
+    } catch (error) {
+      throw new Error(`Failed to load OM state ${statePath}: ${errorMessage(error)}`);
+    }
+  }
+  if (!state || state.version !== STATE_VERSION) {
+    state = {
+      version: STATE_VERSION,
+      enabled: true,
+      sessionId,
+      sessionFile,
+      cwd: ctx.cwd,
+      scope: "session",
+      status: "idle",
+      observations: "",
+      pendingMessageTokens: 0,
+      observationTokens: 0,
+      thresholds: {
+        observation: OBSERVATION_THRESHOLD,
+        reflection: REFLECTION_THRESHOLD,
+        blockAfter: Math.round(OBSERVATION_THRESHOLD * DEFAULT_BLOCK_AFTER_MULTIPLIER),
+        bufferTokens: Math.round(OBSERVATION_THRESHOLD * BUFFER_TOKENS_RATIO),
+        bufferActivation: BUFFER_ACTIVATION_RATIO,
+      },
+      buffered: { observations: [] },
+      updatedAt: new Date().toISOString(),
+    };
+    await saveState(state);
+  }
+  runtime.state = state;
+  return state;
+}
+
+async function saveState(state: PiOMRecord): Promise<void> {
+  if (!runtime.statePath) return;
+  state.updatedAt = new Date().toISOString();
+  await mkdir(dirname(runtime.statePath), { recursive: true });
+  await writeFile(runtime.statePath, JSON.stringify(state, null, 2) + "\n", "utf8");
+  runtime.overlayHandle?.requestRender();
+}
+
+async function refreshCounts(ctx: any): Promise<void> {
+  const state = await ensureState(ctx);
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  const pending = entriesAfter(branch, state.lastObservedEntryId).filter(isMessageLikeEntry);
+  state.pendingMessageTokens = estimateEntriesTokens(pending);
+  state.observationTokens = estimateTokens(state.observations);
+  await saveState(state);
+}
+
+function updateStatus(ctx: any): void {
+  const state = runtime.state;
+  if (!state) return;
+  ctx.ui.setStatus("om", formatShortStatusColored(state));
+  runtime.overlayHandle?.requestRender();
+}
+
+async function observeNow(ctx: any, opts: { force: boolean; reason: string; signal?: AbortSignal; manualText?: string }): Promise<void> {
+  const state = await ensureState(ctx);
+  assertNoOperation(state);
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  const candidates = entriesAfter(branch, state.lastObservedEntryId).filter(isMessageLikeEntry);
+  if (candidates.length === 0 && !opts.manualText) return;
+  const selected = opts.force ? candidates : selectEntriesForObservation(candidates, state);
+  if (selected.length === 0 && !opts.manualText) return;
+  const inputText = opts.manualText ?? formatEntriesForObserver(selected);
+  const startedAt = new Date().toISOString();
+  state.operationLock = { type: "observation", startedAt };
+  state.status = "observing";
+  await saveState(state);
+  updateStatus(ctx);
+  const controller = new AbortController();
+  runtime.currentOperation = controller;
+  const signal = mergeAbortSignals(opts.signal, controller.signal);
+  try {
+    const result = await runObserver(ctx, inputText, signal, { source: opts.reason, existingObservations: state.observations });
+    appendObservations(state, result, estimateTokens(inputText));
+    const last = selected.at(-1);
+    if (last?.id) state.lastObservedEntryId = last.id;
+    state.pendingMessageTokens = Math.max(0, state.pendingMessageTokens - estimateEntriesTokens(selected));
+    state.operationLock = undefined;
+    state.status = "idle";
+    state.lastError = undefined;
+    await writeDebug(ctx, "observation", { startedAt, reason: opts.reason, inputText, rawOutput: result.rawOutput, parsed: result });
+    await saveState(state);
+  } catch (error) {
+    state.operationLock = undefined;
+    state.status = "failed";
+    state.lastError = `Observational Memory Observer failed: ${errorMessage(error)}`;
+    state.lastOperation = { type: "observation", startedAt, endedAt: new Date().toISOString(), inputTokens: estimateTokens(inputText), error: state.lastError };
+    await saveState(state);
+    throw new Error(state.lastError);
+  } finally {
+    runtime.currentOperation = undefined;
+    updateStatus(ctx);
+  }
+}
+
+async function bufferObservation(ctx: any, reason: string): Promise<void> {
+  const state = await ensureState(ctx);
+  if (runtime.currentOperation || state.operationLock) return;
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  const lastBuffered = state.buffered.observations.at(-1)?.endEntryId ?? state.lastObservedEntryId;
+  const candidates = entriesAfter(branch, lastBuffered).filter(isMessageLikeEntry);
+  const tokens = estimateEntriesTokens(candidates);
+  if (tokens < state.thresholds.bufferTokens) return;
+  const selected = takeEntriesUpTo(candidates, Math.min(tokens, OBSERVER_MAX_BATCH_TOKENS));
+  if (selected.length === 0) return;
+  const inputText = formatEntriesForObserver(selected);
+  const startedAt = new Date().toISOString();
+  state.operationLock = { type: "buffer", startedAt };
+  state.status = "buffering";
+  await saveState(state);
+  updateStatus(ctx);
+  const controller = new AbortController();
+  runtime.currentOperation = controller;
+  try {
+    const result = await runObserver(ctx, inputText, controller.signal, { source: reason, existingObservations: state.observations });
+    const observations = result.observations.trim();
+    if (!observations) throw new Error("Observer returned empty buffered observations");
+    state.buffered.observations.push({
+      id: `buf-${Date.now().toString(36)}`,
+      startEntryId: selected[0]?.id,
+      endEntryId: selected.at(-1)!.id,
+      messageTokens: estimateEntriesTokens(selected),
+      observationTokens: estimateTokens(observations),
+      observations,
+      currentTask: result.currentTask,
+      suggestedResponse: result.suggestedContinuation,
+      createdAt: new Date().toISOString(),
+    });
+    state.operationLock = undefined;
+    state.status = "idle";
+    state.lastOperation = { type: "buffer", startedAt, endedAt: new Date().toISOString(), inputTokens: estimateTokens(inputText), outputTokens: estimateTokens(observations), model: DEFAULT_OBSERVATION_MODEL };
+    await writeDebug(ctx, "buffer", { startedAt, reason, inputText, rawOutput: result.rawOutput, parsed: result });
+    await saveState(state);
+  } catch (error) {
+    state.operationLock = undefined;
+    state.status = "failed";
+    state.lastError = `Observational Memory Observer failed: ${errorMessage(error)}`;
+    await saveState(state);
+    throw error;
+  } finally {
+    runtime.currentOperation = undefined;
+    updateStatus(ctx);
+  }
+}
+
+async function activateBuffered(ctx: any, reason: string): Promise<void> {
+  const state = await ensureState(ctx);
+  if (state.buffered.observations.length === 0) return;
+  assertNoOperation(state);
+  const startedAt = new Date().toISOString();
+  state.operationLock = { type: "activation", startedAt };
+  state.status = "observing";
+  const chunks = state.buffered.observations;
+  const activationTarget = state.pendingMessageTokens - state.thresholds.observation * (1 - state.thresholds.bufferActivation);
+  let activatedTokens = 0;
+  const activated: BufferedChunk[] = [];
+  for (const chunk of chunks) {
+    if (activatedTokens < activationTarget || activated.length === 0) {
+      activated.push(chunk);
+      activatedTokens += chunk.messageTokens;
+    }
+  }
+  const observations = activated.map(c => c.observations).join("\n\n").trim();
+  state.observations = [state.observations.trim(), observations].filter(Boolean).join("\n\n");
+  const last = activated.at(-1);
+  if (last) {
+    state.lastObservedEntryId = last.endEntryId;
+    state.currentTask = last.currentTask ?? state.currentTask;
+    state.suggestedResponse = last.suggestedResponse ?? state.suggestedResponse;
+  }
+  state.buffered.observations = chunks.slice(activated.length);
+  state.pendingMessageTokens = Math.max(0, state.pendingMessageTokens - activatedTokens);
+  state.observationTokens = estimateTokens(state.observations);
+  state.lastOperation = { type: "activation", startedAt, endedAt: new Date().toISOString(), inputTokens: activatedTokens, outputTokens: estimateTokens(observations) };
+  state.operationLock = undefined;
+  state.status = "idle";
+  await writeDebug(ctx, "activation", { startedAt, reason, activated: activated.map(c => c.id), observations });
+  await saveState(state);
+  updateStatus(ctx);
+}
+
+async function reflectNow(ctx: any, opts: { reason: string; signal?: AbortSignal; manualPrompt?: string }): Promise<void> {
+  const state = await ensureState(ctx);
+  assertNoOperation(state);
+  if (!state.observations.trim()) throw new Error("No observations to reflect");
+  const startedAt = new Date().toISOString();
+  state.operationLock = { type: "reflection", startedAt };
+  state.status = "reflecting";
+  await saveState(state);
+  updateStatus(ctx);
+  const original = state.observations;
+  const originalTokens = estimateTokens(original);
+  const controller = new AbortController();
+  runtime.currentOperation = controller;
+  const signal = mergeAbortSignals(opts.signal, controller.signal);
+  let lastRaw = "";
+  try {
+    for (let level = 0 as CompressionLevel; level <= 4; level = (level + 1) as CompressionLevel) {
+      const result = await runReflector(ctx, original, level, signal, opts.manualPrompt);
+      lastRaw = result.rawOutput;
+      if (result.degenerate) throw new Error("Reflector output was degenerate/repetitive");
+      if (!result.observations.trim()) throw new Error("Reflector returned empty observations");
+      const reflectedTokens = estimateTokens(result.observations);
+      const compressedEnough = reflectedTokens < Math.min(originalTokens, state.thresholds.reflection);
+      await writeDebug(ctx, `reflection-level-${level}`, { startedAt, reason: opts.reason, originalTokens, reflectedTokens, rawOutput: result.rawOutput, parsed: result });
+      if (compressedEnough || level === 4) {
+        if (!compressedEnough) throw new Error(`Reflector failed to compress below target after level ${level}: ${reflectedTokens} >= ${Math.min(originalTokens, state.thresholds.reflection)}`);
+        state.observations = result.observations;
+        state.currentTask = result.currentTask ?? state.currentTask;
+        state.suggestedResponse = result.suggestedContinuation ?? state.suggestedResponse;
+        state.observationTokens = reflectedTokens;
+        state.operationLock = undefined;
+        state.status = "idle";
+        state.lastError = undefined;
+        state.lastOperation = { type: "reflection", startedAt, endedAt: new Date().toISOString(), inputTokens: originalTokens, outputTokens: reflectedTokens, model: DEFAULT_REFLECTION_MODEL, compressionLevel: level };
+        await saveState(state);
+        return;
+      }
+    }
+  } catch (error) {
+    state.operationLock = undefined;
+    state.status = "failed";
+    state.lastError = `Observational Memory Reflector failed: ${errorMessage(error)}`;
+    state.lastOperation = { type: "reflection", startedAt, endedAt: new Date().toISOString(), inputTokens: originalTokens, error: state.lastError };
+    await writeDebug(ctx, "reflection-failed", { startedAt, reason: opts.reason, error: state.lastError, lastRaw });
+    await saveState(state);
+    throw new Error(state.lastError);
+  } finally {
+    runtime.currentOperation = undefined;
+    updateStatus(ctx);
+  }
+}
+
+async function runObserver(ctx: any, historyText: string, signal: AbortSignal | undefined, opts: { source: string; existingObservations?: string }): Promise<ObserverResult> {
+  const model = resolveModel(ctx, DEFAULT_OBSERVATION_MODEL);
+  const response = await runModel(ctx, model, [
+    { role: "user", content: [{ type: "text", text: buildObserverSystemPrompt() }] },
+    { role: "user", content: [{ type: "text", text: `## New Message History to Observe\n\n${historyText}\n\n---\n\n${buildObserverTaskPrompt(opts.existingObservations, { priorCurrentTask: runtime.state?.currentTask, priorSuggestedResponse: runtime.state?.suggestedResponse })}` }] },
+  ], { temperature: 0.3, maxTokens: 100_000, signal });
+  const text = responseText(response);
+  const parsed = parseObserverOutput(text);
+  if (parsed.degenerate) throw new Error("Observer output was degenerate/repetitive");
+  if (!parsed.observations.trim()) throw new Error("Observer returned no observations");
+  return parsed;
+}
+
+async function runReflector(ctx: any, observations: string, level: CompressionLevel, signal: AbortSignal | undefined, manualPrompt?: string): Promise<ReflectorResult> {
+  const model = resolveModel(ctx, DEFAULT_REFLECTION_MODEL);
+  const response = await runModel(ctx, model, [
+    { role: "user", content: [{ type: "text", text: buildReflectorSystemPrompt() }] },
+    { role: "user", content: [{ type: "text", text: buildReflectorPrompt(observations, level, manualPrompt) }] },
+  ], { temperature: 0, maxTokens: 100_000, signal });
+  const text = responseText(response);
+  return parseReflectorOutput(text);
+}
+
+async function runModel(ctx: any, model: any, messages: any[], opts: { temperature: number; maxTokens: number; signal?: AbortSignal }): Promise<any> {
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) throw new Error(`Auth failed for ${model.provider}/${model.id}: ${auth.error}`);
+  if (!auth.apiKey) throw new Error(`No API key for ${model.provider}/${model.id}`);
+  return complete(model, { messages } as any, { apiKey: auth.apiKey, headers: auth.headers, maxTokens: opts.maxTokens, temperature: opts.temperature, signal: opts.signal } as any);
+}
+
+function resolveModel(ctx: any, modelId: string): any {
+  const slash = modelId.indexOf("/");
+  const provider = slash >= 0 ? modelId.slice(0, slash) : ctx.model?.provider;
+  const id = slash >= 0 ? modelId.slice(slash + 1) : modelId;
+  const model = ctx.modelRegistry.find(provider, id);
+  if (!model) throw new Error(`Could not find OM model ${provider}/${id}`);
+  return model;
+}
+
+function parseObserverOutput(output: string): ObserverResult {
+  if (detectDegenerateRepetition(output)) return { observations: "", rawOutput: output, degenerate: true };
+  const parsed = parseMemorySectionXml(output);
+  return { observations: sanitizeObservationLines(parsed.observations), currentTask: parsed.currentTask || undefined, suggestedContinuation: parsed.suggestedResponse || undefined, rawOutput: output };
+}
+
+function parseReflectorOutput(output: string): ReflectorResult {
+  if (detectDegenerateRepetition(output)) return { observations: "", rawOutput: output, degenerate: true };
+  const parsed = parseMemorySectionXml(output);
+  return { observations: sanitizeObservationLines(parsed.observations), currentTask: parsed.currentTask || undefined, suggestedContinuation: parsed.suggestedResponse || undefined, rawOutput: output };
+}
+
+function parseMemorySectionXml(content: string): { observations: string; currentTask: string; suggestedResponse: string } {
+  const observationsMatches = [...content.matchAll(/^[ \t]*<observations>([\s\S]*?)^[ \t]*<\/observations>/gim)];
+  const observations = observationsMatches.length > 0 ? observationsMatches.map(m => m[1]?.trim() ?? "").filter(Boolean).join("\n") : extractListItemsOnly(content);
+  const currentTask = content.match(/^[ \t]*<current-task>([\s\S]*?)^[ \t]*<\/current-task>/im)?.[1]?.trim() ?? "";
+  const suggestedResponse = content.match(/^[ \t]*<suggested-response>([\s\S]*?)^[ \t]*<\/suggested-response>/im)?.[1]?.trim() ?? "";
+  return { observations, currentTask, suggestedResponse };
+}
+
+function extractListItemsOnly(content: string): string {
+  return content.split("\n").filter(line => /^\s*[-*]\s/.test(line) || /^\s*\d+\.\s/.test(line) || /^\s*Date:\s/i.test(line)).join("\n").trim();
+}
+
+function sanitizeObservationLines(observations: string): string {
+  return observations.split("\n").map(line => line.length > MAX_OBSERVATION_LINE_CHARS ? `${line.slice(0, MAX_OBSERVATION_LINE_CHARS)} … [truncated]` : line).join("\n").trim();
+}
+
+function detectDegenerateRepetition(text: string): boolean {
+  if (!text || text.length < 2000) return false;
+  const windowSize = 200;
+  const step = Math.max(1, Math.floor(text.length / 50));
+  const seen = new Map<string, number>();
+  let duplicates = 0;
+  let total = 0;
+  for (let i = 0; i + windowSize <= text.length; i += step) {
+    const window = text.slice(i, i + windowSize);
+    total++;
+    const count = (seen.get(window) ?? 0) + 1;
+    seen.set(window, count);
+    if (count > 1) duplicates++;
+  }
+  if (total > 5 && duplicates / total > 0.4) return true;
+  return text.split("\n").some(line => line.length > 50_000);
+}
+
+function appendObservations(state: PiOMRecord, result: ObserverResult, inputTokens: number): void {
+  const observations = result.observations.trim();
+  if (!observations) throw new Error("No observations to append");
+  state.observations = [state.observations.trim(), observations].filter(Boolean).join("\n\n");
+  state.currentTask = result.currentTask ?? state.currentTask;
+  state.suggestedResponse = result.suggestedContinuation ?? state.suggestedResponse;
+  state.observationTokens = estimateTokens(state.observations);
+  state.lastOperation = { type: "observation", startedAt: state.operationLock?.startedAt ?? new Date().toISOString(), endedAt: new Date().toISOString(), inputTokens, outputTokens: estimateTokens(observations), model: DEFAULT_OBSERVATION_MODEL };
+}
+
+function buildOMContextMessage(state: PiOMRecord): AgentMessage {
+  const sections = [
+    OBSERVATION_CONTEXT_PROMPT,
+    `<observations>\n${state.observations.trim()}\n</observations>`,
+    OBSERVATION_CONTEXT_INSTRUCTIONS,
+    state.currentTask ? `<current-task>\n${state.currentTask}\n</current-task>` : "",
+    state.suggestedResponse ? `<suggested-response>\n${state.suggestedResponse}\n</suggested-response>` : "",
+    OBSERVATION_RETRIEVAL_INSTRUCTIONS,
+    `<system-reminder>\n${OBSERVATION_CONTINUATION_HINT}\n</system-reminder>`,
+  ].filter(Boolean);
+  return { role: "custom", customType: EXTENSION_ID, display: false, content: sections.join("\n\n"), timestamp: Date.now() };
+}
+
+function buildCompactionSummary(state: PiOMRecord): string {
+  return [
+    "## Observational Memory",
+    "Pi legacy summary compaction was replaced by Mastra-style Observational Memory.",
+    "",
+    "The assistant should use the observations below as memory of prior conversation. Recent raw messages after the compaction boundary remain in context.",
+    "",
+    "<observations>",
+    state.observations.trim(),
+    "</observations>",
+    state.currentTask ? `\n<current-task>\n${state.currentTask}\n</current-task>` : "",
+    state.suggestedResponse ? `\n<suggested-response>\n${state.suggestedResponse}\n</suggested-response>` : "",
+    "",
+    OBSERVATION_CONTEXT_INSTRUCTIONS,
+  ].filter(Boolean).join("\n");
+}
+
+function snapshotDetails(state: PiOMRecord): Record<string, unknown> {
+  return { observationTokens: state.observationTokens, pendingMessageTokens: state.pendingMessageTokens, lastObservedEntryId: state.lastObservedEntryId, currentTask: state.currentTask, suggestedResponse: state.suggestedResponse, thresholds: state.thresholds, lastOperation: state.lastOperation };
+}
+
+function effectiveObservationThreshold(state: PiOMRecord): number {
+  const total = state.thresholds.observation + state.thresholds.reflection;
+  return Math.max(state.thresholds.observation, total - state.observationTokens);
+}
+
+function shouldBuffer(state: PiOMRecord): boolean {
+  if (state.buffered.observations.length === 0) return state.pendingMessageTokens >= state.thresholds.bufferTokens;
+  const bufferedTokens = state.buffered.observations.reduce((sum, c) => sum + c.messageTokens, 0);
+  return state.pendingMessageTokens - bufferedTokens >= state.thresholds.bufferTokens;
+}
+
+function assertNoOperation(state: PiOMRecord): void {
+  if (state.operationLock) throw new Error(`OM operation already active: ${state.operationLock.type} since ${state.operationLock.startedAt}`);
+}
+
+function selectEntriesForObservation(entries: SessionEntry[], state: PiOMRecord): SessionEntry[] {
+  const retentionFloor = state.thresholds.observation * (1 - state.thresholds.bufferActivation);
+  const target = Math.max(0, state.pendingMessageTokens - retentionFloor);
+  if (target <= 0) return [];
+  return takeEntriesUpTo(entries, Math.min(target, OBSERVER_MAX_BATCH_TOKENS));
+}
+
+function takeEntriesUpTo(entries: SessionEntry[], targetTokens: number): SessionEntry[] {
+  const selected: SessionEntry[] = [];
+  let total = 0;
+  for (const entry of entries) {
+    selected.push(entry);
+    total += estimateEntryTokens(entry);
+    if (total >= targetTokens) break;
+  }
+  return selected;
+}
+
+function entriesAfter(branch: SessionEntry[], id?: string): SessionEntry[] {
+  if (!id) return branch;
+  const idx = branch.findIndex(e => e.id === id);
+  return idx >= 0 ? branch.slice(idx + 1) : branch;
+}
+
+function entriesBefore(branch: SessionEntry[], id?: string): SessionEntry[] {
+  if (!id) return branch;
+  const idx = branch.findIndex(e => e.id === id);
+  return idx >= 0 ? branch.slice(0, idx) : branch;
+}
+
+function isMessageLikeEntry(entry: SessionEntry): boolean {
+  return entry.type === "message" || entry.type === "custom_message" || entry.type === "compaction" || entry.type === "branch_summary";
+}
+
+function entryToAgentMessage(entry: SessionEntry): AgentMessage | undefined {
+  if (entry.type === "message") return entry.message;
+  if (entry.type === "custom_message") return { role: "custom", customType: entry.customType, content: entry.content, display: entry.display, details: entry.details, timestamp: Date.parse(entry.timestamp) || Date.now() };
+  if (entry.type === "compaction") return { role: "compactionSummary", summary: entry.summary, tokensBefore: entry.tokensBefore, timestamp: Date.parse(entry.timestamp) || Date.now() };
+  if (entry.type === "branch_summary") return { role: "branchSummary", summary: entry.summary, fromId: entry.fromId, timestamp: Date.parse(entry.timestamp) || Date.now() };
+  return undefined;
+}
+
+function formatEntriesForObserver(entries: SessionEntry[]): string {
+  return entries.map(formatEntryForObserver).filter(Boolean).join("\n\n");
+}
+
+function formatEntryForObserver(entry: SessionEntry): string {
+  const msg = entryToAgentMessage(entry);
+  const createdAt = new Date(entry.timestamp || msg?.timestamp || Date.now());
+  const date = createdAt.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+  const time = createdAt.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+  const body = formatAgentMessage(msg, "observer");
+  return body ? `${date}:\n[entry ${entry.id}] ${time} ${body}` : "";
+}
+
+function formatAgentMessage(msg: any, mode: "observer" | "recall" = "observer", detail: "low" | "high" = "low"): string {
+  if (!msg) return "";
+  const cap = mode === "observer" ? MESSAGE_PART_MAX_CHARS : detail === "high" ? 60_000 : 4_000;
+  switch (msg.role) {
+    case "user": return `User: ${formatContent(msg.content, cap)}`;
+    case "assistant": return `Assistant: ${formatAssistantContent(msg.content, cap)}`;
+    case "toolResult": return `Tool Result ${msg.toolName}: ${truncateText(formatContent(msg.content, cap), detail === "high" ? 60_000 : TOOL_RESULT_MAX_CHARS)}`;
+    case "bashExecution": return `User Bash: ${msg.command}\nOutput: ${truncateText(msg.output ?? "", cap)}${msg.truncated ? "\n[output truncated by Pi]" : ""}`;
+    case "custom": return msg.customType === EXTENSION_ID ? "" : `Custom ${msg.customType}: ${formatContent(msg.content, cap)}`;
+    case "compactionSummary": return `Previous Compaction Summary: ${truncateText(msg.summary ?? "", cap)}`;
+    case "branchSummary": return `Branch Summary: ${truncateText(msg.summary ?? "", cap)}`;
+    default: return `${msg.role ?? "Message"}: ${truncateText(JSON.stringify(msg), cap)}`;
+  }
+}
+
+function formatContent(content: any, cap: number): string {
+  if (typeof content === "string") return truncateText(content, cap);
+  if (!Array.isArray(content)) return truncateText(JSON.stringify(content), cap);
+  return content.map(part => {
+    if (part.type === "text") return part.text;
+    if (part.type === "thinking") return `[Thinking]: ${part.thinking}`;
+    if (part.type === "image") return `[Image: ${part.mimeType ?? "unknown"}]`;
+    if (part.type === "toolCall") return `[Tool Call ${part.name}: ${truncateText(JSON.stringify(part.arguments ?? {}), 2_000)}]`;
+    return `[${part.type}: ${truncateText(JSON.stringify(part), 2_000)}]`;
+  }).join("\n").slice(0, cap);
+}
+
+function formatAssistantContent(content: any, cap: number): string {
+  return formatContent(content, cap);
+}
+
+function serializeEntryForRecall(entry: SessionEntry, detail: "low" | "high"): string {
+  return `[${entry.id}] ${entry.type} ${entry.timestamp}\n${formatAgentMessage(entryToAgentMessage(entry), "recall", detail)}`;
+}
+
+function estimateEntriesTokens(entries: SessionEntry[]): number {
+  return entries.reduce((sum, e) => sum + estimateEntryTokens(e), 0);
+}
+
+function estimateMessagesTokens(messages: any[]): number {
+  return estimateTokens(JSON.stringify(messages));
+}
+
+function estimateEntryTokens(entry: SessionEntry): number {
+  return estimateTokens(formatEntryForObserver(entry) || JSON.stringify(entry));
+}
+
+function estimateTokens(text: string | undefined): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+function truncateText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n... [truncated ${text.length - maxChars} characters]`;
+}
+
+function responseText(response: any): string {
+  if (typeof response?.text === "string") return response.text;
+  if (Array.isArray(response?.content)) return response.content.filter((c: any) => c?.type === "text").map((c: any) => c.text).join("\n");
+  if (typeof response === "string") return response;
+  return "";
+}
+
+function formatShortStatus(state: PiOMRecord): string {
+  if (!state.enabled) return "om: disabled";
+  const msgPct = Math.min(999, Math.round((state.pendingMessageTokens / effectiveObservationThreshold(state)) * 100));
+  const memPct = Math.min(999, Math.round((state.observationTokens / state.thresholds.reflection) * 100));
+  const buffer = state.buffered.observations.length ? ` | buf ${state.buffered.observations.length} ↓${formatTokens(state.buffered.observations.reduce((s, c) => s + c.messageTokens, 0))}` : "";
+  const err = state.status === "failed" && state.lastError ? ` | ${truncateText(state.lastError, 50).replace(/\n/g, " ")}` : "";
+  return `om: ${state.status} | msg ${formatTokens(state.pendingMessageTokens)}/${formatTokens(effectiveObservationThreshold(state))} ${msgPct}% | mem ${formatTokens(state.observationTokens)}/${formatTokens(state.thresholds.reflection)} ${memPct}%${buffer}${err}`;
+}
+
+function formatShortStatusColored(state: PiOMRecord): string {
+  if (!state.enabled) return "\x1b[2;31mom: disabled\x1b[0m";
+  
+  const msgPct = Math.min(999, Math.round((state.pendingMessageTokens / effectiveObservationThreshold(state)) * 100));
+  const memPct = Math.min(999, Math.round((state.observationTokens / state.thresholds.reflection) * 100));
+  
+  let statusColor = "\x1b[32m"; // green for idle
+  if (state.status === "failed") statusColor = "\x1b[91m";
+  else if (state.status !== "idle") statusColor = "\x1b[93m"; // yellow for active ops
+
+  // Highlight percentages
+  const msgPctStr = msgPct >= 80 ? `\x1b[1;91m${msgPct}%\x1b[0m` : msgPct >= 50 ? `\x1b[1;93m${msgPct}%\x1b[0m` : `\x1b[1;32m${msgPct}%\x1b[0m`;
+  const memPctStr = memPct >= 80 ? `\x1b[1;91m${memPct}%\x1b[0m` : memPct >= 50 ? `\x1b[1;93m${memPct}%\x1b[0m` : `\x1b[1;32m${memPct}%\x1b[0m`;
+
+  const buffer = state.buffered.observations.length 
+    ? ` \x1b[2;37m|\x1b[0m buf \x1b[1;36m${state.buffered.observations.length}\x1b[0m \x1b[36m↓${formatTokens(state.buffered.observations.reduce((s, c) => s + c.messageTokens, 0))}\x1b[0m` 
+    : "";
+    
+  const err = state.status === "failed" && state.lastError 
+    ? ` \x1b[2;37m|\x1b[0m \x1b[91m${truncateText(state.lastError, 50).replace(/\n/g, " ")}\x1b[0m` 
+    : "";
+    
+  return `om: ${statusColor}${state.status}\x1b[0m \x1b[2;37m|\x1b[0m msg \x1b[1;33m${formatTokens(state.pendingMessageTokens)}\x1b[0m/\x1b[2;37m${formatTokens(effectiveObservationThreshold(state))}\x1b[0m [${msgPctStr}] \x1b[2;37m|\x1b[0m mem \x1b[1;36m${formatTokens(state.observationTokens)}\x1b[0m/\x1b[2;37m${formatTokens(state.thresholds.reflection)}\x1b[0m [${memPctStr}]${buffer}${err}`;
+}
+
+function formatDetailedStatus(state: PiOMRecord): string {
+  return `${formatShortStatus(state)}\nlastObservedEntryId: ${state.lastObservedEntryId ?? "none"}\ncurrentTask: ${state.currentTask ?? "none"}\nsuggestedResponse: ${state.suggestedResponse ?? "none"}\nlastOperation: ${state.lastOperation ? JSON.stringify(state.lastOperation, null, 2) : "none"}\nstatePath: ${runtime.statePath ?? "unknown"}`;
+}
+
+function formatMemoryText(state: PiOMRecord): string {
+  return [`# Observational Memory`, formatShortStatus(state), ``, `## Current Task`, state.currentTask ?? "", ``, `## Suggested Response`, state.suggestedResponse ?? "", ``, `## Observations`, state.observations || "No observations yet.", ``, state.lastError ? `## Last Error\n${state.lastError}` : ""].join("\n");
+}
+
+function formatDetailedStatusColored(state: PiOMRecord): string[] {
+  const lines: string[] = [];
+  lines.push(`\x1b[1;36m█ SYSTEM STATUS\x1b[0m`);
+  lines.push(formatShortStatusColored(state));
+  lines.push(``);
+  lines.push(`\x1b[1;33mSession ID:\x1b[0m \x1b[37m${state.sessionId}\x1b[0m`);
+  lines.push(`\x1b[1;33mLast Observed Entry ID:\x1b[0m \x1b[2;37m${state.lastObservedEntryId ?? "none"}\x1b[0m`);
+  lines.push(``);
+  lines.push(`\x1b[1;35mThresholds:\x1b[0m`);
+  lines.push(`  - Observation: \x1b[1;32m${formatTokens(state.thresholds.observation)}\x1b[0m tokens`);
+  lines.push(`  - Reflection: \x1b[1;32m${formatTokens(state.thresholds.reflection)}\x1b[0m tokens`);
+  lines.push(`  - Block After: \x1b[1;32m${formatTokens(state.thresholds.blockAfter)}\x1b[0m tokens`);
+  lines.push(`  - Buffer Size: \x1b[1;32m${formatTokens(state.thresholds.bufferTokens)}\x1b[0m tokens`);
+  lines.push(``);
+  lines.push(`\x1b[1;35mLast Operation:\x1b[0m`);
+  if (state.lastOperation) {
+    const op = state.lastOperation;
+    lines.push(`  - Type: \x1b[1;36m${op.type}\x1b[0m`);
+    lines.push(`  - Model: \x1b[2;37m${op.model ?? "unknown"}\x1b[0m`);
+    lines.push(`  - Timing: \x1b[2;37m${op.startedAt} → ${op.endedAt ?? "running"}\x1b[0m`);
+    lines.push(`  - Input Tokens: \x1b[1;33m${op.inputTokens}\x1b[0m`);
+    if (op.outputTokens) lines.push(`  - Output Tokens: \x1b[1;32m${op.outputTokens}\x1b[0m`);
+    if (op.compressionLevel !== undefined) lines.push(`  - Compression Level: \x1b[1;33m${op.compressionLevel}\x1b[0m`);
+    if (op.error) lines.push(`  - Error: \x1b[91m${op.error}\x1b[0m`);
+  } else {
+    lines.push(`  \x1b[2;37mNo operation executed yet.\x1b[0m`);
+  }
+  lines.push(``);
+  lines.push(`\x1b[1;33mState File:\x1b[0m \x1b[2;37m${runtime.statePath ?? "unknown"}\x1b[0m`);
+  return lines;
+}
+
+function highlightObservations(text: string): string[] {
+  const lines = text.split("\n");
+  return lines.map(line => {
+    // 1. Highlight Date
+    if (line.startsWith("Date: ")) {
+      const dateVal = line.slice(6).trim();
+      return `\x1b[1;35m📅 ${dateVal}\x1b[0m`;
+    }
+    
+    // 2. Match Bullet points
+    // Format: * 🔴 (14:30) User stated X
+    const bulletMatch = line.match(/^(\s*)\*\s*(🔴|🟡|🟢|✅)?\s*(\(\d{2}:\d{2}\))?\s*(.*)$/);
+    if (bulletMatch) {
+      const [_, indent, emoji, time, rest] = bulletMatch;
+      let colorReset = "\x1b[0m";
+      let bulletColor = "";
+      let timeColor = "";
+      let textStyle = "";
+      
+      if (emoji === "🔴") {
+        bulletColor = "\x1b[91m🔴\x1b[0m";
+        timeColor = time ? `\x1b[1;91m${time}\x1b[0m` : "";
+        textStyle = "\x1b[37m"; // Bright White/Normal for text
+      } else if (emoji === "🟡") {
+        bulletColor = "\x1b[93m🟡\x1b[0m";
+        timeColor = time ? `\x1b[1;93m${time}\x1b[0m` : "";
+        textStyle = "\x1b[37m";
+      } else if (emoji === "🟢") {
+        bulletColor = "\x1b[32m🟢\x1b[0m";
+        timeColor = time ? `\x1b[2;32m${time}\x1b[0m` : "";
+        textStyle = "\x1b[2;37m"; // Dim text for low priority
+      } else if (emoji === "✅") {
+        bulletColor = "\x1b[92m✅\x1b[0m";
+        timeColor = time ? `\x1b[1;92m${time}\x1b[0m` : "";
+        textStyle = "\x1b[32m"; // Green text for completed
+      } else {
+        bulletColor = "\x1b[2;36m•\x1b[0m";
+        timeColor = time ? `\x1b[2;37m${time}\x1b[0m` : "";
+        textStyle = "\x1b[0m";
+      }
+
+      let content = rest || "";
+      // Highlight sub-bullets or arrows
+      if (content.startsWith("->")) {
+        content = `\x1b[2;36m└──\x1b[0m ` + content.slice(2).trim();
+      }
+
+      // Highlight key terms: User stated, User requested, User asked, Agent, etc.
+      content = content
+        .replace(/(User stated|User requested|User asked)/gi, "\x1b[1;33m$1\x1b[0m" + textStyle)
+        .replace(/(Agent|Assistant|Observer|Reflector)/gi, "\x1b[1;36m$1\x1b[0m" + textStyle)
+        .replace(/(failed|error|crash)/gi, "\x1b[1;31m$1\x1b[0m" + textStyle)
+        .replace(/(success|resolved|complete|passed)/gi, "\x1b[1;32m$1\x1b[0m" + textStyle);
+
+      return `${indent}${bulletColor} ${timeColor} ${textStyle}${content}\x1b[0m`;
+    }
+
+    return line;
+  });
+}
+
+function formatMemoryTextColored(state: PiOMRecord): string[] {
+  const lines: string[] = [];
+  
+  // Header
+  lines.push(`\x1b[1;36m█ OBSERVATIONAL MEMORY\x1b[0m`);
+  lines.push(formatShortStatusColored(state));
+  lines.push(``);
+  
+  // Current Task
+  lines.push(`\x1b[1;93m◆ CURRENT TASK\x1b[0m`);
+  if (state.currentTask) {
+    lines.push(`\x1b[37m${state.currentTask}\x1b[0m`);
+  } else {
+    lines.push(`\x1b[2;37mNo current task specified.\x1b[0m`);
+  }
+  lines.push(``);
+  
+  // Suggested Response
+  lines.push(`\x1b[1;92m◆ SUGGESTED RESPONSE\x1b[0m`);
+  if (state.suggestedResponse) {
+    lines.push(`\x1b[37m${state.suggestedResponse}\x1b[0m`);
+  } else {
+    lines.push(`\x1b[2;37mNo suggested response.\x1b[0m`);
+  }
+  lines.push(``);
+  
+  // Observations
+  lines.push(`\x1b[1;96m◆ OBSERVATIONS\x1b[0m`);
+  if (state.observations) {
+    lines.push(...highlightObservations(state.observations));
+  } else {
+    lines.push(`\x1b[2;37mNo observations yet.\x1b[0m`);
+  }
+  
+  if (state.lastError) {
+    lines.push(``);
+    lines.push(`\x1b[1;91m▲ LAST ERROR\x1b[0m`);
+    lines.push(`\x1b[31m${state.lastError}\x1b[0m`);
+  }
+  
+  return lines;
+}
+
+function formatDebugTabColored(state: PiOMRecord): string[] {
+  const lines: string[] = [];
+  lines.push(`\x1b[1;31m█ DIAGNOSTICS & BUFFER\x1b[0m`);
+  lines.push(``);
+  lines.push(`\x1b[1;33mState Path:\x1b[0m \x1b[2;37m${runtime.statePath ?? "unknown"}\x1b[0m`);
+  lines.push(`\x1b[1;33mDebug Dir:\x1b[0m  \x1b[2;37m${runtime.debugDir ?? "unknown"}\x1b[0m`);
+  lines.push(`\x1b[1;33mLock:\x1b[0m       ${state.operationLock ? `\x1b[1;31m${state.operationLock.type}\x1b[0m \x1b[2;37msince ${state.operationLock.startedAt}\x1b[0m` : "\x1b[2;32mnone\x1b[0m"}`);
+  lines.push(``);
+  lines.push(`\x1b[1;35mBuffered Chunks (${state.buffered.observations.length}):\x1b[0m`);
+  if (state.buffered.observations.length > 0) {
+    for (const c of state.buffered.observations) {
+      lines.push(`  \x1b[1;36m• ${c.id}\x1b[0m: \x1b[33m${formatTokens(c.messageTokens)} msg\x1b[0m → \x1b[32m${formatTokens(c.observationTokens)} obs\x1b[0m \x1b[2;37m(end ${c.endEntryId})\x1b[0m`);
+    }
+  } else {
+    lines.push(`  \x1b[2;37mBuffer is empty.\x1b[0m`);
+  }
+  lines.push(``);
+  if (state.lastError) {
+    lines.push(`\x1b[1;91mlastError:\x1b[0m`);
+    lines.push(`\x1b[31m${state.lastError}\x1b[0m`);
+  } else {
+    lines.push(`\x1b[2;32mNo errors reported.\x1b[0m`);
+  }
+  return lines;
+}
+
+
+
+function formatTokens(tokens: number): string {
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(tokens >= 10_000 ? 0 : 1)}k`;
+  return String(tokens);
+}
+
+async function writeDebug(ctx: any, name: string, payload: unknown): Promise<void> {
+  const state = await ensureState(ctx);
+  const dir = runtime.debugDir ?? join(ctx.cwd, CONFIG_DIR_NAME, "om", "debug");
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, `${new Date().toISOString().replace(/[:.]/g, "-")}-${sanitizeFileName(name)}.json`);
+  await writeFile(file, JSON.stringify({ extension: EXTENSION_ID, sessionId: state.sessionId, ...payload as any }, null, 2) + "\n", "utf8");
+}
+
+function sanitizeFileName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 160) || "session";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function mergeAbortSignals(a?: AbortSignal, b?: AbortSignal): AbortSignal | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (a.aborted || b.aborted) controller.abort();
+  a.addEventListener("abort", abort, { once: true });
+  b.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+
+class OMOverlay {
+  private scroll = 0;
+  private tab: "memory" | "status" | "debug" = "memory";
+  constructor(private getState: () => PiOMRecord | undefined, private close: () => void, private requestRender: () => void = () => {}, private theme?: any) {}
+  invalidate(): void {}
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape) || data === "q") return this.close();
+    if (matchesKey(data, Key.left)) this.tab = this.tab === "debug" ? "status" : "memory";
+    else if (matchesKey(data, Key.right)) this.tab = this.tab === "memory" ? "status" : "debug";
+    else if (data === "1") this.tab = "memory";
+    else if (data === "2") this.tab = "status";
+    else if (data === "3") this.tab = "debug";
+    else if (matchesKey(data, Key.up)) this.scroll = Math.max(0, this.scroll - 1);
+    else if (matchesKey(data, Key.down)) this.scroll += 1;
+    else if (matchesKey(data, Key.home)) this.scroll = 0;
+    else if (matchesKey(data, Key.end)) this.scroll = 1_000_000;
+    this.requestRender();
+  }
+  render(width: number): string[] {
+    const state = this.getState();
+    const w = Math.max(20, width);
+    const title = ` Observational Memory — ${this.tab.toUpperCase()} `;
+    const border = "─".repeat(Math.max(0, w - 2));
+    const top = `┌${truncateToWidth(title + border, w - 1, "")}┐`;
+    const bottom = `└${border}┘`;
+    
+    // Header tab row
+    const tabMemory = this.tab === "memory" ? "\x1b[1;30;47m MEMORY [1] \x1b[0m" : "\x1b[2;37m MEMORY [1] \x1b[0m";
+    const tabStatus = this.tab === "status" ? "\x1b[1;30;47m STATUS [2] \x1b[0m" : "\x1b[2;37m STATUS [2] \x1b[0m";
+    const tabDebug = this.tab === "debug" ? "\x1b[1;30;47m DIAGNOSTICS [3] \x1b[0m" : "\x1b[2;37m DIAGNOSTICS [3] \x1b[0m";
+    const tabsRow = ` ${tabMemory} │ ${tabStatus} │ ${tabDebug} `;
+
+    const content = state ? this.content(state) : ["No OM state loaded."];
+    const bodyWidth = Math.max(1, w - 4);
+    
+    // Add tab row and a visual separator line
+    const fullContent = [
+      tabsRow,
+      `\x1b[2;37m` + "─".repeat(bodyWidth) + `\x1b[0m`,
+      ...content
+    ];
+
+    const wrapped = fullContent.flatMap(line => wrapTextWithAnsi(line || " ", bodyWidth));
+    const maxBody = 28;
+    const maxScroll = Math.max(0, wrapped.length - maxBody);
+    this.scroll = Math.min(this.scroll, maxScroll);
+    const visible = wrapped.slice(this.scroll, this.scroll + maxBody);
+    const lines = [top];
+    for (const line of visible) lines.push(`│ ${truncateToWidth(line, bodyWidth, "").padEnd(bodyWidth)} │`);
+    while (lines.length < maxBody + 1) lines.push(`│ ${" ".repeat(bodyWidth)} │`);
+    const help = "←/→/1-3 tabs • ↑/↓ scroll • home/end • q/esc close";
+    lines.push(`│ ${truncateToWidth(help, bodyWidth, "").padEnd(bodyWidth)} │`);
+    lines.push(bottom);
+    return lines.map(line => truncateToWidth(line, w, ""));
+  }
+  private content(state: PiOMRecord): string[] {
+    if (this.tab === "status") return formatDetailedStatusColored(state);
+    if (this.tab === "debug") return formatDebugTabColored(state);
+    return formatMemoryTextColored(state);
+  }
+}