pi-observational-memory-extension 0.1.2 → 0.2.0

package/extensions/index.ts

@@ -7,12 +7,14 @@ import {
 } 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 { copyFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const EXTENSION_ID = "pi-observational-memory";
-const STATE_VERSION = 1;
+const STATE_VERSION = 3;
 const DEFAULT_OBSERVATION_MODEL = "google/gemini-2.5-flash";
 const DEFAULT_REFLECTION_MODEL = "google/gemini-2.5-flash";
 const OBSERVATION_THRESHOLD = 30_000;
@@ -25,6 +27,14 @@ 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 STALE_OPERATION_LOCK_MS = 15 * 60 * 1000;
+const PREVIOUS_OBSERVATIONS_MAX_TOKENS = 2_000;
+const ATOMIC_BACKUP_SUFFIX = ".bak";
+const MAX_ATTACHMENT_OBSERVE_BYTES = 2_000_000;
+const VECTOR_TOP_K_DEFAULT = 6;
+const VECTOR_THRESHOLD_DEFAULT = 0.12;
+const PROJECT_REFERENCES_MAX_TOKENS = 2_000;
+const VECTOR_MAX_INDEX_CHUNKS = 2_000;
 
 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.
@@ -49,6 +59,29 @@ Your memory is comprised of observations which may mention raw message IDs. The
 
 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 CAVEMAN_OM_INSTRUCTION = `Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Use full caveman compression style.
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact. Leave out the words "agent" and "assistant" at the start of each observation line, it is assumed each line is referring to the assistant unless it specifically says it was about the user. Leave out parenthesis and other text characters like * that would not contribute to understanding the observations.
+
+Pattern: \`[thing] [action] [reason]. [next step]\`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use < not <=. Fix:"
+
+Example 1
+🔴 14:31 user asks why React component rerenders
+🟡 14:32 saw inline object prop create new ref each render, cause rerender
+✅ 14:34 fixed render issue by wrap object in useMemo
+
+Example 2
+🟡 15:10 explained pool reuse DB connections, skip repeat handshake overhead
+
+Don't say "Agent did x", say "did x". It will be assumed the agent did what was observed. The who should only be specified for the user or other third parties: "user asked x"
+
+Drop caveman for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question, and anything that requires remembering verbatim content. Resume caveman after clear part done`;
+
 const OBSERVER_EXTRACTION_INSTRUCTIONS = `CRITICAL: DISTINGUISH USER ASSERTIONS FROM QUESTIONS
 
 When the user TELLS you something about themselves, mark it as an assertion:
@@ -165,7 +198,8 @@ const OBSERVER_GUIDELINES = `- Be specific enough for the assistant to act on
 - 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 {
+function buildObserverSystemPrompt(caveman = false): string {
+  const cavemanInstruction = caveman ? `\n\n${CAVEMAN_OM_INSTRUCTION}` : "";
   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:
@@ -188,20 +222,22 @@ Do NOT add thread identifiers, thread IDs, or <thread> tags to your observations
 
 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.`;
+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.${cavemanInstruction}`;
 }
 
 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 limitedExisting = limitTextByTokens(existingObservations, PREVIOUS_OBSERVATIONS_MAX_TOKENS);
+  const previousWasTruncated = Boolean(existingObservations?.trim()) && limitedExisting !== existingObservations;
+  if (limitedExisting?.trim()) {
+    prompt += `## Previous Observations\n\n${limitedExisting}\n\n---\n\nDo not repeat these existing observations. Your new observations will be appended to the existing observations. Previous observations may be truncated to the most recent/relevant tail for context budget safety.\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) {
+    if (opts.wasTruncated || previousWasTruncated) {
       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`;
@@ -210,7 +246,8 @@ function buildObserverTaskPrompt(existingObservations: string | undefined, opts:
   return prompt;
 }
 
-function buildReflectorSystemPrompt(): string {
+function buildReflectorSystemPrompt(caveman = false): string {
+  const cavemanInstruction = caveman ? `\n\n${CAVEMAN_OM_INSTRUCTION}` : "";
   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.
@@ -258,7 +295,7 @@ State current task(s) explicitly: primary and secondary pending tasks. Mark wait
 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.`;
+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.${cavemanInstruction}`;
 }
 
 type CompressionLevel = 0 | 1 | 2 | 3 | 4;
@@ -292,6 +329,22 @@ type BufferedChunk = {
   createdAt: string;
 };
 
+type ObserveAttachmentsMode = "auto" | "on" | "off";
+type RetrievalProvider = "off" | "local" | "gemini";
+
+type PiOMSettings = {
+  observationModel: string;
+  reflectionModel: string;
+  caveman: boolean;
+  observeAttachments: ObserveAttachmentsMode;
+  retrieval: {
+    provider: RetrievalProvider;
+    model: string;
+    topK: number;
+    threshold: number;
+  };
+};
+
 type PiOMRecord = {
   version: number;
   enabled: boolean;
@@ -307,13 +360,32 @@ type PiOMRecord = {
   pendingMessageTokens: number;
   observationTokens: number;
   thresholds: { observation: number; reflection: number; blockAfter: number; bufferTokens: number; bufferActivation: number };
+  settings: PiOMSettings;
   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;
+  vectorIndex?: VectorIndexState;
+  updatedAt: string;
+};
+
+type VectorIndexEntry = {
+  id: string;
+  hash: string;
+  text: string;
+  embedding: number[];
+  tokens: number;
+  createdAt: string;
+};
+
+type VectorIndexState = {
+  provider: RetrievalProvider;
+  model: string;
+  scopeKey: string;
   updatedAt: string;
+  entries: VectorIndexEntry[];
 };
 
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
@@ -335,6 +407,61 @@ type Runtime = {
 
 const runtime: Runtime = { failureCount: 0 };
 
+let checkedForUpdate = false;
+let updateNotification: string | undefined = undefined;
+
+function isNewerVersion(local: string, latest: string): boolean {
+  const localParts = local.split(".").map((x) => parseInt(x, 10) || 0);
+  const latestParts = latest.split(".").map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const localPart = localParts[i] ?? 0;
+    const latestPart = latestParts[i] ?? 0;
+    if (latestPart > localPart) return true;
+    if (latestPart < localPart) return false;
+  }
+  return false;
+}
+
+async function checkForUpdates(ctx: any) {
+  try {
+    const extensionDir = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(extensionDir, "..", "package.json");
+    if (!existsSync(pkgPath)) return;
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    const localVersion = pkg.version;
+    if (!localVersion) return;
+
+    if (typeof fetch === "undefined") return;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+    try {
+      const res = await fetch("https://registry.npmjs.org/pi-observational-memory-extension/latest", {
+        signal: controller.signal,
+        headers: {
+          "User-Agent": `pi-observational-memory-update-checker/${localVersion}`
+        }
+      });
+      clearTimeout(timeoutId);
+
+      if (!res.ok) return;
+      const data = (await res.json()) as { version?: string };
+      const latestVersion = data.version;
+      if (!latestVersion) return;
+
+      if (isNewerVersion(localVersion, latestVersion)) {
+        updateNotification = `A new version of pi-observational-memory-extension is available: v${latestVersion} (installed: v${localVersion}). Please update using npm to get the latest features!`;
+        ctx?.ui?.notify?.(updateNotification, "warning");
+      }
+    } catch {
+      clearTimeout(timeoutId);
+    }
+  } catch {
+    // Fail silently
+  }
+}
+
 export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "om_recall",
@@ -373,6 +500,13 @@ export default function (pi: ExtensionAPI) {
     await refreshCounts(ctx);
     updateStatus(ctx);
     runtime.statusTimer = setInterval(() => updateStatus(ctx), 1000);
+
+    if (!checkedForUpdate) {
+      checkedForUpdate = true;
+      checkForUpdates(ctx).catch(() => {});
+    } else if (updateNotification) {
+      ctx?.ui?.notify?.(updateNotification, "warning");
+    }
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
@@ -436,7 +570,10 @@ export default function (pi: ExtensionAPI) {
       .filter(isMessageLikeEntry)
       .map(entryToAgentMessage)
       .filter(Boolean) as AgentMessage[];
-    const omMessage = buildOMContextMessage(state);
+    const queryText = unobserved.map(m => formatAgentMessage(m)).join("\n\n");
+    const retrieved = await retrieveRelevantObservations(ctx, state, queryText);
+    const projectReferences = await buildProjectReferences(ctx, state);
+    const omMessage = buildOMContextMessage(state, retrieved, projectReferences);
     const finalMessages = [omMessage, ...unobserved];
     if (finalMessages.length <= 1) return { messages: [omMessage, ...event.messages.slice(-8)] };
     return { messages: finalMessages };
@@ -565,6 +702,92 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("om", {
+    description: "Manage Observational Memory settings. Usage: /om, /om set <key> <value>, /om enable|disable|observe|reflect|memory",
+    handler: async (args, ctx) => {
+      const state = await ensureState(ctx);
+      const input = (args || "").trim();
+      if (!input || input === "status") {
+        await refreshCounts(ctx);
+        ctx.ui.notify(formatSettingsText(state), state.status === "failed" ? "error" : "info");
+        updateStatus(ctx);
+        return;
+      }
+      const [cmd, ...rest] = input.split(/\s+/);
+      if (cmd === "enable") {
+        state.enabled = true;
+        state.status = "idle";
+        await saveState(state);
+        updateStatus(ctx);
+        ctx.ui.notify("Observational Memory enabled", "info");
+        return;
+      }
+      if (cmd === "disable") {
+        state.enabled = false;
+        state.status = "disabled";
+        await saveState(state);
+        updateStatus(ctx);
+        ctx.ui.notify("Observational Memory disabled", "warning");
+        return;
+      }
+      if (cmd === "observe") {
+        await observeNow(ctx, { force: true, reason: "manual" });
+        updateStatus(ctx);
+        ctx.ui.notify("OM observation complete", "info");
+        return;
+      }
+      if (cmd === "reflect") {
+        await reflectNow(ctx, { reason: "manual", manualPrompt: rest.join(" ") || undefined });
+        updateStatus(ctx);
+        ctx.ui.notify("OM reflection complete", "info");
+        return;
+      }
+      if (cmd === "memory") {
+        ctx.ui.notify(formatMemoryText(state), "info");
+        return;
+      }
+      if (cmd === "vector") {
+        const sub = rest[0] || "status";
+        if (sub === "status") {
+          ctx.ui.notify(formatVectorStatus(state), "info");
+          return;
+        }
+        if (sub === "rebuild") {
+          await rebuildVectorIndex(ctx, state);
+          await saveState(state);
+          ctx.ui.notify(formatVectorStatus(state), "info");
+          return;
+        }
+        if (sub === "search") {
+          const query = rest.slice(1).join(" ").trim();
+          if (!query) throw new Error("Usage: /om vector search <query>");
+          const result = await retrieveRelevantObservations(ctx, state, query);
+          ctx.ui.notify(result || "No matching OM vector results.", "info");
+          return;
+        }
+        throw new Error("Unknown /om vector command. Use /om vector status|rebuild|search <query>");
+      }
+      if (cmd === "set") {
+        const key = rest[0];
+        const value = rest.slice(1).join(" ");
+        applySetting(state, key, value);
+        await saveState(state);
+        updateStatus(ctx);
+        ctx.ui.notify(`OM setting updated: ${key}=${value}`, "info");
+        return;
+      }
+      if (cmd === "reset") {
+        state.thresholds = defaultThresholds();
+        state.settings = defaultSettings();
+        await saveState(state);
+        updateStatus(ctx);
+        ctx.ui.notify("OM settings reset to defaults", "info");
+        return;
+      }
+      throw new Error(`Unknown /om command: ${cmd}. Use /om, /om set <key> <value>, /om enable|disable|observe|reflect|memory|reset`);
+    },
+  });
+
   pi.registerCommand("om-compact", {
     description: "Run Pi compaction; pi-observational-memory will replace the summary with OM.",
     handler: async (args, ctx) => {
@@ -644,53 +867,289 @@ async function ensureState(ctx: any): Promise<PiOMRecord> {
   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;
+  const legacyStatePath = join(dir, `${sanitizeFileName(sessionId)}.json`);
   runtime.debugDir = debugDir;
   let state: PiOMRecord | undefined;
-  if (existsSync(statePath)) {
+  let statePath = legacyStatePath;
+  if (existsSync(legacyStatePath)) {
     try {
-      state = JSON.parse(await readFile(statePath, "utf8")) as PiOMRecord;
+      state = normalizeState(JSON.parse(await readFile(legacyStatePath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
     } catch (error) {
-      throw new Error(`Failed to load OM state ${statePath}: ${errorMessage(error)}`);
+      const backupPath = `${legacyStatePath}${ATOMIC_BACKUP_SUFFIX}`;
+      if (existsSync(backupPath)) {
+        try {
+          state = normalizeState(JSON.parse(await readFile(backupPath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
+        } catch {
+          console.error(`[OM] Error: Failed to parse state and backup for ${legacyStatePath}. Falling back to default empty state.`);
+          try {
+            await rename(legacyStatePath, `${legacyStatePath}.corrupted`);
+            await rename(backupPath, `${backupPath}.corrupted`);
+          } catch {}
+        }
+      } else {
+        console.error(`[OM] Error: Failed to parse state for ${legacyStatePath} (no backup). Falling back to default empty state.`);
+        try {
+          await rename(legacyStatePath, `${legacyStatePath}.corrupted`);
+        } catch {}
+      }
     }
   }
-  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);
+  if (!state) {
+    state = createDefaultState({ sessionId, sessionFile, cwd: ctx.cwd });
   }
+  statePath = statePathFor(ctx.cwd, state.scope, sessionId);
+  if (statePath !== legacyStatePath && existsSync(statePath)) {
+    try {
+      state = normalizeState(JSON.parse(await readFile(statePath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
+    } catch {
+      const backupPath = `${statePath}${ATOMIC_BACKUP_SUFFIX}`;
+      if (existsSync(backupPath)) {
+        try {
+          state = normalizeState(JSON.parse(await readFile(backupPath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
+        } catch {
+          try {
+            await rename(statePath, `${statePath}.corrupted`);
+            await rename(backupPath, `${backupPath}.corrupted`);
+          } catch {}
+        }
+      } else {
+        try {
+          await rename(statePath, `${statePath}.corrupted`);
+        } catch {}
+      }
+    }
+  }
+  const resolvedStatePath = statePathFor(ctx.cwd, state.scope, sessionId);
+  if (resolvedStatePath !== statePath && existsSync(resolvedStatePath)) {
+    statePath = resolvedStatePath;
+    try {
+      state = normalizeState(JSON.parse(await readFile(statePath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
+    } catch {
+      const backupPath = `${statePath}${ATOMIC_BACKUP_SUFFIX}`;
+      if (existsSync(backupPath)) {
+        try {
+          state = normalizeState(JSON.parse(await readFile(backupPath, "utf8")), { sessionId, sessionFile, cwd: ctx.cwd });
+        } catch {
+          try {
+            await rename(statePath, `${statePath}.corrupted`);
+            await rename(backupPath, `${backupPath}.corrupted`);
+          } catch {}
+        }
+      } else {
+        try {
+          await rename(statePath, `${statePath}.corrupted`);
+        } catch {}
+      }
+    }
+  } else {
+    statePath = resolvedStatePath;
+  }
+  runtime.statePath = statePath;
+  const recovered = recoverStaleOperationLock(state);
   runtime.state = state;
+  if (recovered || state.version !== STATE_VERSION || !existsSync(statePath)) await saveState(state);
   return state;
 }
 
+function defaultSettings(): PiOMSettings {
+  return {
+    observationModel: DEFAULT_OBSERVATION_MODEL,
+    reflectionModel: DEFAULT_REFLECTION_MODEL,
+    caveman: false,
+    observeAttachments: "auto",
+    retrieval: { provider: "off", model: "local/hash-bow-v1", topK: VECTOR_TOP_K_DEFAULT, threshold: VECTOR_THRESHOLD_DEFAULT },
+  };
+}
+
+function defaultThresholds(): PiOMRecord["thresholds"] {
+  return {
+    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,
+  };
+}
+
+function createDefaultState(identity: { sessionId: string; sessionFile?: string; cwd: string }): PiOMRecord {
+  return {
+    version: STATE_VERSION,
+    enabled: true,
+    sessionId: identity.sessionId,
+    sessionFile: identity.sessionFile,
+    cwd: identity.cwd,
+    scope: "session",
+    status: "idle",
+    observations: "",
+    pendingMessageTokens: 0,
+    observationTokens: 0,
+    thresholds: defaultThresholds(),
+    settings: defaultSettings(),
+    buffered: { observations: [] },
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function normalizeState(raw: any, identity: { sessionId: string; sessionFile?: string; cwd: string }): PiOMRecord {
+  const defaults = createDefaultState(identity);
+  const state = {
+    ...defaults,
+    ...raw,
+    version: STATE_VERSION,
+    sessionId: raw?.sessionId || identity.sessionId,
+    sessionFile: raw?.sessionFile || identity.sessionFile,
+    cwd: raw?.cwd || identity.cwd,
+    thresholds: { ...defaults.thresholds, ...(raw?.thresholds ?? {}) },
+    settings: normalizeSettings(raw?.settings, defaults.settings),
+    buffered: { observations: [], ...(raw?.buffered ?? {}) },
+  } as PiOMRecord;
+  state.observations = redactSecrets(String(state.observations ?? ""));
+  state.currentTask = state.currentTask ? redactSecrets(state.currentTask) : undefined;
+  state.suggestedResponse = state.suggestedResponse ? redactSecrets(state.suggestedResponse) : undefined;
+  state.lastError = state.lastError ? redactSecrets(state.lastError) : undefined;
+  state.scope = state.scope === "project" ? "project" : "session";
+  state.observationTokens = estimateTokens(state.observations);
+  state.vectorIndex = normalizeVectorIndex(state.vectorIndex, state);
+  return state;
+}
+
+function normalizeSettings(raw: any, defaults: PiOMSettings): PiOMSettings {
+  const legacyAttachments = raw?.observeAttachments;
+  let observeAttachments: ObserveAttachmentsMode = defaults.observeAttachments;
+  if (legacyAttachments === true) observeAttachments = "on";
+  else if (legacyAttachments === false) observeAttachments = "off";
+  else if (["auto", "on", "off"].includes(String(legacyAttachments))) observeAttachments = legacyAttachments;
+  const rawRetrieval = raw?.retrieval ?? {};
+  const provider = ["off", "local", "gemini"].includes(String(rawRetrieval.provider)) ? rawRetrieval.provider as RetrievalProvider : defaults.retrieval.provider;
+  return {
+    ...defaults,
+    ...raw,
+    observeAttachments,
+    retrieval: {
+      provider,
+      model: String(rawRetrieval.model || (provider === "gemini" ? "gemini-embedding-001" : defaults.retrieval.model)),
+      topK: clampInt(Number(rawRetrieval.topK ?? defaults.retrieval.topK), 1, 30),
+      threshold: clampNumber(Number(rawRetrieval.threshold ?? defaults.retrieval.threshold), 0, 1),
+    },
+  };
+}
+
+function normalizeVectorIndex(raw: any, state: PiOMRecord): VectorIndexState | undefined {
+  if (!raw || typeof raw !== "object" || !Array.isArray(raw.entries)) return undefined;
+  return {
+    provider: ["off", "local", "gemini"].includes(String(raw.provider)) ? raw.provider : state.settings.retrieval.provider,
+    model: String(raw.model || state.settings.retrieval.model),
+    scopeKey: String(raw.scopeKey || scopeKeyForState(state)),
+    updatedAt: String(raw.updatedAt || new Date().toISOString()),
+    entries: raw.entries.slice(-VECTOR_MAX_INDEX_CHUNKS).filter((e: any) => e && typeof e.text === "string" && Array.isArray(e.embedding)),
+  };
+}
+
+function clampInt(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function clampNumber(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, value));
+}
+
+function statePathFor(cwd: string, scope: PiOMRecord["scope"], sessionId: string): string {
+  const base = join(cwd, CONFIG_DIR_NAME, "om", scope === "project" ? "projects" : "sessions");
+  return join(base, `${scope === "project" ? projectHashForCwd(cwd) : sanitizeFileName(sessionId)}.json`);
+}
+
+function projectHashForCwd(cwd: string): string {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+
+function scopeKeyForState(state: PiOMRecord): string {
+  return state.scope === "project" ? `project:${projectHashForCwd(state.cwd)}` : `session:${sanitizeFileName(state.sessionId)}`;
+}
+
+function isStaleOperationLock(lock: PiOMRecord["operationLock"], now = Date.now()): boolean {
+  if (!lock) return false;
+  const started = Date.parse(lock.startedAt);
+  return Number.isFinite(started) && now - started > STALE_OPERATION_LOCK_MS;
+}
+
+function recoverStaleOperationLock(state: PiOMRecord, now = Date.now()): boolean {
+  if (!isStaleOperationLock(state.operationLock, now)) return false;
+  const lock = state.operationLock!;
+  state.lastOperation = { type: lock.type, startedAt: lock.startedAt, endedAt: new Date(now).toISOString(), inputTokens: 0, error: `Recovered stale OM operation lock after ${Math.round((now - Date.parse(lock.startedAt)) / 1000)}s` };
+  state.lastError = state.lastOperation.error;
+  state.operationLock = undefined;
+  state.status = state.enabled ? "idle" : "disabled";
+  return true;
+}
+
 async function saveState(state: PiOMRecord): Promise<void> {
+  runtime.statePath = statePathFor(state.cwd, state.scope, state.sessionId);
   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");
+  state.observations = redactSecrets(state.observations);
+  if (state.currentTask) state.currentTask = redactSecrets(state.currentTask);
+  if (state.suggestedResponse) state.suggestedResponse = redactSecrets(state.suggestedResponse);
+  if (state.lastError) state.lastError = redactSecrets(state.lastError);
+  if (state.settings.retrieval.provider === "local") state.vectorIndex = buildLocalVectorIndex(state);
+  await mergeExistingScopeState(runtime.statePath, state);
+  await atomicWriteJson(runtime.statePath, state);
+  if (state.scope === "project") {
+    const sessionPointerPath = statePathFor(state.cwd, "session", state.sessionId);
+    const sessionPointer = { ...state, scope: "project" as const, observations: "", currentTask: undefined, suggestedResponse: undefined, vectorIndex: undefined };
+    await atomicWriteJson(sessionPointerPath, sessionPointer);
+  }
+  await saveVectorIndex(state);
   runtime.overlayHandle?.requestRender();
 }
 
+
+async function mergeExistingScopeState(filePath: string, state: PiOMRecord): Promise<void> {
+  if (!existsSync(filePath)) return;
+  try {
+    const existing = normalizeState(JSON.parse(await readFile(filePath, "utf8")), { sessionId: state.sessionId, sessionFile: state.sessionFile, cwd: state.cwd });
+    if (existing.updatedAt === state.updatedAt) return;
+    const merged = suppressDuplicateObservations(state.observations, existing.observations);
+    if (merged) state.observations = [state.observations.trim(), merged].filter(Boolean).join("\n\n");
+    state.currentTask = state.currentTask ?? existing.currentTask;
+    state.suggestedResponse = state.suggestedResponse ?? existing.suggestedResponse;
+    state.observationTokens = estimateTokens(state.observations);
+  } catch {
+    // Corrupt existing state is handled by .bak recovery during load; do not block saving current valid state.
+  }
+}
+
+async function saveVectorIndex(state: PiOMRecord): Promise<void> {
+  if (!state.vectorIndex || !runtime.statePath) return;
+  const dir = join(dirname(dirname(runtime.statePath)), "vectors");
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, `${sanitizeFileName(state.vectorIndex.scopeKey)}.jsonl`);
+  const lines = state.vectorIndex.entries.map(entry => JSON.stringify(redactDeep(entry))).join("\n") + (state.vectorIndex.entries.length ? "\n" : "");
+  await writeFile(file, lines, "utf8");
+}
+
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  const backupPath = `${filePath}${ATOMIC_BACKUP_SUFFIX}`;
+  const json = JSON.stringify(redactDeep(value), null, 2) + "\n";
+  await writeFile(tmpPath, json, "utf8");
+  if (existsSync(filePath)) {
+    try {
+      await copyFile(filePath, backupPath);
+    } catch {
+      // Backup is best-effort; rename below is the durability boundary.
+    }
+  }
+  try {
+    await rename(tmpPath, filePath);
+  } catch (error) {
+    try { await unlink(tmpPath); } catch {}
+    throw error;
+  }
+}
+
 async function refreshCounts(ctx: any): Promise<void> {
   let isStale = false;
   try {
@@ -735,7 +1194,10 @@ async function observeNow(ctx: any, opts: { force: boolean; reason: string; sign
   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 observerInput = opts.manualText
+    ? { text: opts.manualText, attachmentParts: [] as any[], omissions: [] as string[] }
+    : buildObserverInput(ctx, selected, state);
+  const inputText = observerInput.text;
   const startedAt = new Date().toISOString();
   state.operationLock = { type: "observation", startedAt };
   state.status = "observing";
@@ -745,7 +1207,7 @@ async function observeNow(ctx: any, opts: { force: boolean; reason: string; sign
   runtime.currentOperation = controller;
   const signal = mergeAbortSignals(opts.signal, controller.signal);
   try {
-    const result = await runObserver(ctx, inputText, signal, { source: opts.reason, existingObservations: state.observations });
+    const result = await runObserver(ctx, inputText, signal, { source: opts.reason, existingObservations: state.observations, attachmentParts: observerInput.attachmentParts });
     appendObservations(state, result, estimateTokens(inputText));
     const last = selected.at(-1);
     if (last?.id) state.lastObservedEntryId = last.id;
@@ -753,7 +1215,7 @@ async function observeNow(ctx: any, opts: { force: boolean; reason: string; sign
     state.operationLock = undefined;
     state.status = "idle";
     state.lastError = undefined;
-    await writeDebug(ctx, "observation", { startedAt, reason: opts.reason, inputText, rawOutput: result.rawOutput, parsed: result });
+    await writeDebug(ctx, "observation", { startedAt, reason: opts.reason, inputText, attachmentOmissions: observerInput.omissions, attachmentCount: observerInput.attachmentParts.length, rawOutput: result.rawOutput, parsed: result });
     await saveState(state);
   } catch (error) {
     state.operationLock = undefined;
@@ -778,7 +1240,8 @@ async function bufferObservation(ctx: any, reason: string): Promise<void> {
   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 observerInput = buildObserverInput(ctx, selected, state);
+  const inputText = observerInput.text;
   const startedAt = new Date().toISOString();
   state.operationLock = { type: "buffer", startedAt };
   state.status = "buffering";
@@ -787,7 +1250,7 @@ async function bufferObservation(ctx: any, reason: string): Promise<void> {
   const controller = new AbortController();
   runtime.currentOperation = controller;
   try {
-    const result = await runObserver(ctx, inputText, controller.signal, { source: reason, existingObservations: state.observations });
+    const result = await runObserver(ctx, inputText, controller.signal, { source: reason, existingObservations: state.observations, attachmentParts: observerInput.attachmentParts });
     const observations = result.observations.trim();
     if (!observations) throw new Error("Observer returned empty buffered observations");
     state.buffered.observations.push({
@@ -803,8 +1266,8 @@ async function bufferObservation(ctx: any, reason: string): Promise<void> {
     });
     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 });
+    state.lastOperation = { type: "buffer", startedAt, endedAt: new Date().toISOString(), inputTokens: estimateTokens(inputText), outputTokens: estimateTokens(observations), model: state.settings.observationModel || DEFAULT_OBSERVATION_MODEL };
+    await writeDebug(ctx, "buffer", { startedAt, reason, inputText, attachmentOmissions: observerInput.omissions, attachmentCount: observerInput.attachmentParts.length, rawOutput: result.rawOutput, parsed: result });
     await saveState(state);
   } catch (error) {
     state.operationLock = undefined;
@@ -854,6 +1317,7 @@ async function activateBuffered(ctx: any, reason: string): Promise<void> {
   state.buffered.observations = chunks.slice(activated.length);
   state.pendingMessageTokens = Math.max(0, state.pendingMessageTokens - activatedTokens);
   state.observationTokens = estimateTokens(state.observations);
+  state.vectorIndex = buildLocalVectorIndex(state);
   state.lastOperation = { type: "activation", startedAt, endedAt: new Date().toISOString(), inputTokens: activatedTokens, outputTokens: estimateTokens(observations) };
   state.operationLock = undefined;
   state.status = "idle";
@@ -900,10 +1364,11 @@ async function reflectNow(ctx: any, opts: { reason: string; signal?: AbortSignal
         state.currentTask = result.currentTask ?? state.currentTask;
         state.suggestedResponse = result.suggestedContinuation ?? state.suggestedResponse;
         state.observationTokens = reflectedTokens;
+        state.vectorIndex = buildLocalVectorIndex(state);
         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 };
+        state.lastOperation = { type: "reflection", startedAt, endedAt: new Date().toISOString(), inputTokens: originalTokens, outputTokens: reflectedTokens, model: state.settings.reflectionModel || DEFAULT_REFLECTION_MODEL, compressionLevel: level };
         await saveState(state);
         return;
       }
@@ -922,11 +1387,16 @@ async function reflectNow(ctx: any, opts: { reason: string; signal?: AbortSignal
   }
 }
 
-async function runObserver(ctx: any, historyText: string, signal: AbortSignal | undefined, opts: { source: string; existingObservations?: string }): Promise<ObserverResult> {
-  const model = resolveModel(ctx, DEFAULT_OBSERVATION_MODEL);
+async function runObserver(ctx: any, historyText: string, signal: AbortSignal | undefined, opts: { source: string; existingObservations?: string; attachmentParts?: any[] }): Promise<ObserverResult> {
+  const state = await ensureState(ctx);
+  const modelId = state.settings.observationModel || DEFAULT_OBSERVATION_MODEL;
+  const model = resolveModel(ctx, modelId);
   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 })}` }] },
+    { role: "user", content: [{ type: "text", text: buildObserverSystemPrompt(state.settings.caveman) }] },
+    { 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 })}` },
+      ...(opts.attachmentParts ?? []),
+    ] },
   ], { temperature: 0.3, maxTokens: 100_000, signal });
   const text = responseText(response);
   const parsed = parseObserverOutput(text);
@@ -936,9 +1406,11 @@ async function runObserver(ctx: any, historyText: string, signal: AbortSignal |
 }
 
 async function runReflector(ctx: any, observations: string, level: CompressionLevel, signal: AbortSignal | undefined, manualPrompt?: string): Promise<ReflectorResult> {
-  const model = resolveModel(ctx, DEFAULT_REFLECTION_MODEL);
+  const state = await ensureState(ctx);
+  const modelId = state.settings.reflectionModel || DEFAULT_REFLECTION_MODEL;
+  const model = resolveModel(ctx, modelId);
   const response = await runModel(ctx, model, [
-    { role: "user", content: [{ type: "text", text: buildReflectorSystemPrompt() }] },
+    { role: "user", content: [{ type: "text", text: buildReflectorSystemPrompt(state.settings.caveman) }] },
     { role: "user", content: [{ type: "text", text: buildReflectorPrompt(observations, level, manualPrompt) }] },
   ], { temperature: 0, maxTokens: 100_000, signal });
   const text = responseText(response);
@@ -956,7 +1428,11 @@ 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);
+  const currentModel = ctx.model;
+  if (currentModel && String(currentModel.provider) === String(provider) && String(currentModel.id ?? currentModel.model) === String(id)) {
+    return currentModel;
+  }
+  const model = typeof ctx.modelRegistry?.find === "function" ? ctx.modelRegistry.find(provider, id) : undefined;
   if (!model) throw new Error(`Could not find OM model ${provider}/${id}`);
   return model;
 }
@@ -986,7 +1462,7 @@ function extractListItemsOnly(content: string): string {
 }
 
 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();
+  return redactSecrets(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 {
@@ -1008,19 +1484,207 @@ function detectDegenerateRepetition(text: string): boolean {
 }
 
 function appendObservations(state: PiOMRecord, result: ObserverResult, inputTokens: number): void {
-  const observations = result.observations.trim();
-  if (!observations) throw new Error("No observations to append");
+  const observations = suppressDuplicateObservations(state.observations, result.observations.trim());
+  if (!observations) throw new Error("No new non-duplicate 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 };
+  state.vectorIndex = buildLocalVectorIndex(state);
+  state.lastOperation = { type: "observation", startedAt: state.operationLock?.startedAt ?? new Date().toISOString(), endedAt: new Date().toISOString(), inputTokens, outputTokens: estimateTokens(observations), model: state.settings.observationModel || DEFAULT_OBSERVATION_MODEL };
+}
+
+function observationChunks(text: string): string[] {
+  return text.split(/\n{2,}/).flatMap(block => {
+    const lines = block.split("\n").map(l => l.trim()).filter(Boolean);
+    if (lines.length <= 1) return lines;
+    return lines.some(l => /^[-*]\s|^[🔴🟡🟢✅]/.test(l)) ? lines : [lines.join("\n")];
+  }).map(redactSecrets).filter(Boolean);
+}
+
+function normalizeForSimilarity(text: string): string {
+  return text.toLowerCase().replace(/[🔴🟡🟢✅]/g, "").replace(/\([^)]*\)/g, "").replace(/[^a-z0-9а-яё\s._/-]/gi, " ").replace(/\s+/g, " ").trim();
+}
+
+function textHash(text: string): string {
+  return createHash("sha256").update(normalizeForSimilarity(text)).digest("hex");
 }
 
-function buildOMContextMessage(state: PiOMRecord): AgentMessage {
+function localEmbedding(text: string): number[] {
+  const dims = 128;
+  const vec = new Array(dims).fill(0);
+  const words = normalizeForSimilarity(text).split(" ").filter(w => w.length > 2);
+  for (const word of words) {
+    const h = createHash("sha256").update(word).digest();
+    const idx = h[0] % dims;
+    vec[idx] += 1 + Math.min(3, word.length / 8);
+  }
+  const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0)) || 1;
+  return vec.map(v => Number((v / norm).toFixed(6)));
+}
+
+function cosine(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length);
+  let sum = 0;
+  for (let i = 0; i < n; i++) sum += (a[i] ?? 0) * (b[i] ?? 0);
+  return sum;
+}
+
+function suppressDuplicateObservations(existing: string, incoming: string): string {
+  const existingChunks = observationChunks(existing);
+  const existingHashes = new Set(existingChunks.map(textHash));
+  const existingEmbeddings = existingChunks.map(localEmbedding);
+  const kept: string[] = [];
+  for (const chunk of observationChunks(incoming)) {
+    const hash = textHash(chunk);
+    if (existingHashes.has(hash)) continue;
+    const emb = localEmbedding(chunk);
+    if (existingEmbeddings.some(e => cosine(e, emb) >= 0.94)) continue;
+    existingHashes.add(hash);
+    existingEmbeddings.push(emb);
+    kept.push(chunk);
+  }
+  return kept.join("\n").trim();
+}
+
+function buildLocalVectorIndex(state: PiOMRecord): VectorIndexState | undefined {
+  if (state.settings.retrieval.provider === "off") return undefined;
+  const provider = state.settings.retrieval.provider;
+  if (provider !== "local") return state.vectorIndex;
+  const now = new Date().toISOString();
+  const entries = observationChunks(state.observations).slice(-VECTOR_MAX_INDEX_CHUNKS).map((text, i) => ({
+    id: `obs-${i}-${textHash(text).slice(0, 10)}`,
+    hash: textHash(text),
+    text,
+    embedding: localEmbedding(text),
+    tokens: estimateTokens(text),
+    createdAt: now,
+  }));
+  return { provider: "local", model: state.settings.retrieval.model, scopeKey: scopeKeyForState(state), updatedAt: now, entries };
+}
+
+async function retrieveRelevantObservations(ctx: any, state: PiOMRecord, query: string): Promise<string> {
+  const cfg = state.settings.retrieval;
+  if (cfg.provider === "off" || !query.trim()) return "";
+  if (cfg.provider === "gemini") return retrieveGeminiObservations(ctx, state, query);
+  const index = state.vectorIndex?.provider === "local" ? state.vectorIndex : buildLocalVectorIndex(state);
+  if (!index || index.entries.length === 0) return "";
+  state.vectorIndex = index;
+  const queryVec = localEmbedding(query);
+  return index.entries
+    .map(entry => ({ entry, score: cosine(queryVec, entry.embedding) }))
+    .filter(x => x.score >= cfg.threshold)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, cfg.topK)
+    .map(x => `- (${x.score.toFixed(2)}) ${x.entry.text}`)
+    .join("\n");
+}
+
+async function retrieveGeminiObservations(ctx: any, state: PiOMRecord, query: string): Promise<string> {
+  const apiKey = process.env.GOOGLE_GENERATIVE_AI_API_KEY || process.env.GEMINI_API_KEY;
+  if (!apiKey) throw new Error("OM Gemini retrieval requires GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY");
+  const chunks = observationChunks(state.observations).slice(-VECTOR_MAX_INDEX_CHUNKS);
+  if (chunks.length === 0) return "";
+  const queryVec = await geminiEmbedding(apiKey, state.settings.retrieval.model, query);
+  const entries = await Promise.all(chunks.map(async (text, i) => ({
+    id: `gem-${i}-${textHash(text).slice(0, 10)}`,
+    hash: textHash(text),
+    text,
+    embedding: await geminiEmbedding(apiKey, state.settings.retrieval.model, text),
+    tokens: estimateTokens(text),
+    createdAt: new Date().toISOString(),
+  })));
+  state.vectorIndex = { provider: "gemini", model: state.settings.retrieval.model, scopeKey: scopeKeyForState(state), updatedAt: new Date().toISOString(), entries };
+  return entries
+    .map(entry => ({ entry, score: cosine(queryVec, entry.embedding) }))
+    .filter(x => x.score >= state.settings.retrieval.threshold)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, state.settings.retrieval.topK)
+    .map(x => `- (${x.score.toFixed(2)}) ${x.entry.text}`)
+    .join("\n");
+}
+
+async function geminiEmbedding(apiKey: string, model: string, text: string): Promise<number[]> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:embedContent?key=${encodeURIComponent(apiKey)}`;
+  const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ content: { parts: [{ text: truncateText(redactSecrets(text), 20_000) }] } }) });
+  if (!res.ok) throw new Error(`Gemini embedding failed: HTTP ${res.status} ${truncateText(await res.text(), 300)}`);
+  const json = await res.json() as any;
+  const values = json?.embedding?.values;
+  if (!Array.isArray(values)) throw new Error("Gemini embedding response did not include embedding.values");
+  const norm = Math.sqrt(values.reduce((s: number, v: number) => s + v * v, 0)) || 1;
+  return values.map((v: number) => v / norm);
+}
+
+
+async function buildProjectReferences(ctx: any, state: PiOMRecord): Promise<string> {
+  if (state.scope !== "project") return "";
+  const sessionsDir = join(ctx.cwd, CONFIG_DIR_NAME, "om", "sessions");
+  if (!existsSync(sessionsDir)) return "";
+  let files: string[] = [];
+  try {
+    files = (await readdir(sessionsDir)).filter(f => f.endsWith(".json") && f !== `${sanitizeFileName(state.sessionId)}.json`);
+  } catch {
+    return "";
+  }
+  const records: PiOMRecord[] = [];
+  for (const file of files.slice(-20)) {
+    try {
+      const raw = JSON.parse(await readFile(join(sessionsDir, file), "utf8"));
+      const normalized = normalizeState(raw, { sessionId: raw.sessionId || file.replace(/\.json$/, ""), sessionFile: raw.sessionFile, cwd: ctx.cwd });
+      if (normalized.observations.trim()) records.push(normalized);
+    } catch {
+      // Skip unreadable references; main state remains authoritative.
+    }
+  }
+  records.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+  const blocks: string[] = [];
+  let tokens = 0;
+  for (const rec of records.slice(0, 5)) {
+    const obs = limitTextByTokens(rec.observations, 500) || "";
+    const block = `<other-session id="${sanitizeFileName(rec.sessionId)}" updated="${rec.updatedAt}">\n${obs}\n</other-session>`;
+    tokens += estimateTokens(block);
+    if (tokens > PROJECT_REFERENCES_MAX_TOKENS) break;
+    blocks.push(block);
+  }
+  return blocks.join("\n\n");
+}
+
+async function rebuildVectorIndex(ctx: any, state: PiOMRecord): Promise<void> {
+  if (state.settings.retrieval.provider === "off") {
+    state.vectorIndex = undefined;
+    return;
+  }
+  if (state.settings.retrieval.provider === "local") {
+    state.vectorIndex = buildLocalVectorIndex(state);
+    return;
+  }
+  if (state.settings.retrieval.provider === "gemini") {
+    await retrieveGeminiObservations(ctx, state, state.observations.slice(0, 2_000) || "build index");
+    return;
+  }
+}
+
+function formatVectorStatus(state: PiOMRecord): string {
+  const idx = state.vectorIndex;
+  return [
+    "OM vector retrieval",
+    `provider: ${state.settings.retrieval.provider}`,
+    `model: ${state.settings.retrieval.model}`,
+    `scopeKey: ${scopeKeyForState(state)}`,
+    `topK: ${state.settings.retrieval.topK}`,
+    `threshold: ${state.settings.retrieval.threshold}`,
+    `index: ${idx ? `${idx.entries.length} entries, updated ${idx.updatedAt}` : "not built"}`,
+  ].join("\n");
+}
+
+function buildOMContextMessage(state: PiOMRecord, retrievedObservations = "", projectReferences = ""): AgentMessage {
+  const retrievalBlock = retrievedObservations ? `<relevant-observations>\n${retrievedObservations}\n</relevant-observations>` : "";
+  const projectBlock = projectReferences ? `<other-sessions>\n${projectReferences}\n</other-sessions>` : "";
   const sections = [
     OBSERVATION_CONTEXT_PROMPT,
     `<observations>\n${state.observations.trim()}\n</observations>`,
+    retrievalBlock,
+    projectBlock,
     OBSERVATION_CONTEXT_INSTRUCTIONS,
     state.currentTask ? `<current-task>\n${state.currentTask}\n</current-task>` : "",
     state.suggestedResponse ? `<suggested-response>\n${state.suggestedResponse}\n</suggested-response>` : "",
@@ -1112,6 +1776,99 @@ function formatEntriesForObserver(entries: SessionEntry[]): string {
   return entries.map(formatEntryForObserver).filter(Boolean).join("\n\n");
 }
 
+function buildObserverInput(ctx: any, entries: SessionEntry[], state: PiOMRecord): { text: string; attachmentParts: any[]; omissions: string[] } {
+  const model = resolveModel(ctx, state.settings.observationModel || DEFAULT_OBSERVATION_MODEL);
+  const attachmentParts: any[] = [];
+  const omissions: string[] = [];
+  const text = entries.map(entry => formatEntryForObserverWithAttachments(entry, state, model, attachmentParts, omissions)).filter(Boolean).join("\n\n");
+  return { text, attachmentParts, omissions };
+}
+
+function formatEntryForObserverWithAttachments(entry: SessionEntry, state: PiOMRecord, model: any, attachmentParts: any[], omissions: string[]): 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 = formatAgentMessageForObserverWithAttachments(msg, state, model, attachmentParts, omissions);
+  return body ? `${date}:\n[entry ${entry.id}] ${time} ${body}` : "";
+}
+
+function formatAgentMessageForObserverWithAttachments(msg: any, state: PiOMRecord, model: any, attachmentParts: any[], omissions: string[]): string {
+  if (!msg) return "";
+  const cap = MESSAGE_PART_MAX_CHARS;
+  switch (msg.role) {
+    case "user": return `User: ${formatContentForObserverWithAttachments(msg.content, cap, state, model, attachmentParts, omissions)}`;
+    case "assistant": return `Assistant: ${formatContentForObserverWithAttachments(msg.content, cap, state, model, attachmentParts, omissions)}`;
+    case "toolResult": return `Tool Result ${msg.toolName}: ${truncateText(formatContentForObserverWithAttachments(msg.content, cap, state, model, attachmentParts, omissions), 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}: ${formatContentForObserverWithAttachments(msg.content, cap, state, model, attachmentParts, omissions)}`;
+    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(redactDeep(msg)), cap)}`;
+  }
+}
+
+function formatContentForObserverWithAttachments(content: any, cap: number, state: PiOMRecord, model: any, attachmentParts: any[], omissions: string[]): string {
+  if (typeof content === "string") return truncateText(redactSecrets(content), cap);
+  if (!Array.isArray(content)) return truncateText(redactSecrets(JSON.stringify(redactDeep(content))), cap);
+  return content.map(part => {
+    if (part.type === "text") return redactSecrets(part.text);
+    if (part.type === "thinking") return `[Thinking]: ${redactSecrets(part.thinking ?? "")}`;
+    if (isAttachmentPart(part)) return handleObserverAttachmentPart(part, state, model, attachmentParts, omissions);
+    if (part.type === "toolCall") return `[Tool Call ${part.name}: ${truncateText(redactSecrets(JSON.stringify(redactDeep(part.arguments ?? {}))), 2_000)}]`;
+    return `[${part.type}: ${truncateText(redactSecrets(JSON.stringify(redactDeep(part))), 2_000)}]`;
+  }).join("\n").slice(0, cap);
+}
+
+function isAttachmentPart(part: any): boolean {
+  return part?.type === "image" || part?.type === "file" || Boolean(part?.mimeType || part?.mediaType || part?.source?.mediaType);
+}
+
+function modelSupportsAttachments(model: any): boolean {
+  const provider = String(model?.provider || "").toLowerCase();
+  const id = String(model?.id || model?.model || "").toLowerCase();
+  if (provider.includes("google") || provider.includes("gemini")) return id.includes("gemini");
+  if (provider.includes("openai")) return /gpt-4o|gpt-4\.1|o3|o4/.test(id);
+  if (provider.includes("anthropic")) return /claude-3|claude-sonnet-4|claude-opus-4/.test(id);
+  return false;
+}
+
+function handleObserverAttachmentPart(part: any, state: PiOMRecord, model: any, attachmentParts: any[], omissions: string[]): string {
+  const mode = state.settings.observeAttachments;
+  const mime = String(part.mimeType || part.mediaType || part.source?.mediaType || "unknown").toLowerCase();
+  const raw = part.data || part.image || part.source?.data || "";
+  const approxBytes = typeof raw === "string" ? Math.ceil(raw.length * 0.75) : 0;
+  const label = `${mime}${approxBytes ? `, ~${approxBytes} bytes` : ""}`;
+  if (mode === "off") return `[Attachment omitted: observation disabled; ${label}]`;
+  if (!mime.startsWith("image/")) {
+    const reason = `unsupported mime ${mime}`;
+    omissions.push(reason);
+    return `[Attachment omitted: ${reason}; ${label}]`;
+  }
+  if (approxBytes > MAX_ATTACHMENT_OBSERVE_BYTES) {
+    const reason = `attachment too large ${approxBytes} > ${MAX_ATTACHMENT_OBSERVE_BYTES} bytes`;
+    if (mode === "on") throw new Error(`OM attachment observation failed: ${reason}`);
+    omissions.push(reason);
+    return `[Attachment omitted: ${reason}; ${label}]`;
+  }
+  if (!modelSupportsAttachments(model)) {
+    const reason = `unsupported observer model ${model?.provider ?? "unknown"}/${model?.id ?? "unknown"}`;
+    if (mode === "on") throw new Error(`OM attachment observation failed: ${reason}`);
+    omissions.push(reason);
+    return `[Attachment omitted: ${reason}; ${label}]`;
+  }
+  const normalized = normalizeAttachmentPartForModel(part);
+  attachmentParts.push(normalized);
+  return `[Attachment included for Observer: ${label}]`;
+}
+
+function normalizeAttachmentPartForModel(part: any): any {
+  const mimeType = part.mimeType || part.mediaType || part.source?.mediaType;
+  const data = part.data || part.image || part.source?.data;
+  if (part.type === "image") return { ...part, mimeType, data };
+  return { type: "image", mimeType, data };
+}
+
 function formatEntryForObserver(entry: SessionEntry): string {
   const msg = entryToAgentMessage(entry);
   const createdAt = new Date(entry.timestamp || msg?.timestamp || Date.now());
@@ -1136,15 +1893,72 @@ function formatAgentMessage(msg: any, mode: "observer" | "recall" = "observer",
   }
 }
 
+
+function limitTextByTokens(text: string | undefined, maxTokens: number): string | undefined {
+  if (!text) return text;
+  if (estimateTokens(text) <= maxTokens) return text;
+  const maxChars = Math.max(0, maxTokens * 4);
+  const tail = text.slice(Math.max(0, text.length - maxChars));
+  const lineBoundary = tail.indexOf("\n");
+  const trimmedTail = lineBoundary >= 0 ? tail.slice(lineBoundary + 1) : tail;
+  return `[Earlier observations truncated for observer prompt safety: kept last ~${maxTokens} tokens.]\n${trimmedTail}`;
+}
+
+function redactSecrets(input: string): string {
+  if (!input) return input;
+  return input
+    .replace(/npm_[A-Za-z0-9]{16,}/g, "[REDACTED_NPM_TOKEN]")
+    .replace(/github_pat_[A-Za-z0-9_]{20,}/g, "[REDACTED_GITHUB_TOKEN]")
+    .replace(/gh[pousr]_[A-Za-z0-9_]{20,}/g, "[REDACTED_GITHUB_TOKEN]")
+    .replace(/sk-[A-Za-z0-9_-]{20,}/g, "[REDACTED_API_KEY]")
+    .replace(/(?<=(?:\b|["'])(?:api[_-]?key|token|secret|password)(?:\b|["'])\s*[:=]\s*["']?)[^"'\s,;}]{8,}/gi, "[REDACTED_SECRET]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/gi, "Bearer [REDACTED_TOKEN]");
+}
+
+function isSensitiveObjectKey(key: string): boolean {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+  return /^(api-?key|authorization|auth-?token|access-?token|refresh-?token|secret|password|bearer)$/i.test(normalized);
+}
+
+function redactDeep<T>(value: T): T {
+  if (typeof value === "string") return redactSecrets(value) as T;
+  if (Array.isArray(value)) return value.map(item => redactDeep(item)) as T;
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = isSensitiveObjectKey(key) ? "[REDACTED_SECRET]" : redactDeep(child);
+    }
+    return out as T;
+  }
+  return value;
+}
+
+function shouldObserveAttachment(part: any, state?: PiOMRecord): boolean {
+  const mode = state?.settings.observeAttachments ?? "auto";
+  if (mode === "off") return false;
+  const mime = String(part.mimeType || part.mediaType || "").toLowerCase();
+  if (mode === "auto" && mime && !mime.startsWith("image/")) return false;
+  const raw = part.data || part.image || part.source?.data || "";
+  const approxBytes = typeof raw === "string" ? Math.ceil(raw.length * 0.75) : 0;
+  return approxBytes <= MAX_ATTACHMENT_OBSERVE_BYTES;
+}
+
+function formatAttachmentPart(part: any): string {
+  const mime = part.mimeType || part.mediaType || "unknown";
+  const raw = part.data || part.image || part.source?.data || "";
+  const approxBytes = typeof raw === "string" ? Math.ceil(raw.length * 0.75) : 0;
+  return `[Attachment observed: ${mime}${approxBytes ? `, ~${approxBytes} bytes` : ""}]`;
+}
+
 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);
+  if (typeof content === "string") return truncateText(redactSecrets(content), cap);
+  if (!Array.isArray(content)) return truncateText(redactSecrets(JSON.stringify(redactDeep(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)}]`;
+    if (part.type === "text") return redactSecrets(part.text);
+    if (part.type === "thinking") return `[Thinking]: ${redactSecrets(part.thinking ?? "")}`;
+    if (part.type === "image") return shouldObserveAttachment(part, runtime.state) ? formatAttachmentPart(part) : "[Image omitted: attachment observation disabled or unsupported]";
+    if (part.type === "toolCall") return `[Tool Call ${part.name}: ${truncateText(redactSecrets(JSON.stringify(redactDeep(part.arguments ?? {}))), 2_000)}]`;
+    return `[${part.type}: ${truncateText(redactSecrets(JSON.stringify(redactDeep(part))), 2_000)}]`;
   }).join("\n").slice(0, cap);
 }
 
@@ -1179,9 +1993,9 @@ function truncateText(text: string, maxChars: number): string {
 }
 
 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;
+  if (typeof response?.text === "string") return redactSecrets(response.text);
+  if (Array.isArray(response?.content)) return redactSecrets(response.content.filter((c: any) => c?.type === "text").map((c: any) => c.text).join("\n"));
+  if (typeof response === "string") return redactSecrets(response);
   return "";
 }
 
@@ -1219,6 +2033,101 @@ function formatShortStatusColored(state: PiOMRecord): string {
   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 parsePositiveIntSetting(key: string, value: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`OM setting ${key} must be a positive number`);
+  return Math.round(n);
+}
+
+function parseRatioSetting(key: string, value: string): number {
+  const raw = value.trim();
+  const n = raw.endsWith("%") ? Number(raw.slice(0, -1)) / 100 : Number(raw);
+  if (!Number.isFinite(n) || n <= 0 || n > 1) throw new Error(`OM setting ${key} must be a ratio between 0 and 1, or percent like 80%`);
+  return n;
+}
+
+function parseBooleanSetting(key: string, value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on", "enabled"].includes(normalized)) return true;
+  if (["0", "false", "no", "off", "disabled"].includes(normalized)) return false;
+  throw new Error(`OM setting ${key} must be on/off or true/false`);
+}
+
+function parseAttachmentSetting(key: string, value: string): ObserveAttachmentsMode {
+  const normalized = value.trim().toLowerCase();
+  if (["auto", "default"].includes(normalized)) return "auto";
+  if (["1", "true", "yes", "on", "enabled"].includes(normalized)) return "on";
+  if (["0", "false", "no", "off", "disabled"].includes(normalized)) return "off";
+  throw new Error(`OM setting ${key} must be auto/on/off`);
+}
+
+function parseRetrievalProvider(key: string, value: string): RetrievalProvider {
+  const normalized = value.trim().toLowerCase();
+  if (["off", "local", "gemini"].includes(normalized)) return normalized as RetrievalProvider;
+  throw new Error(`OM setting ${key} must be off, local, or gemini`);
+}
+
+function applySetting(state: PiOMRecord, key: string | undefined, value: string): void {
+  if (!key) throw new Error("Missing OM setting key");
+  if (!value) throw new Error(`Missing OM setting value for ${key}`);
+  const normalized = key.toLowerCase().replace(/_/g, "-");
+  if (["observation", "observation-threshold", "observe-threshold"].includes(normalized)) state.thresholds.observation = parsePositiveIntSetting(key, value);
+  else if (["reflection", "reflection-threshold", "reflect-threshold"].includes(normalized)) state.thresholds.reflection = parsePositiveIntSetting(key, value);
+  else if (["block-after", "blockafter"].includes(normalized)) state.thresholds.blockAfter = parsePositiveIntSetting(key, value);
+  else if (["buffer", "buffer-tokens"].includes(normalized)) state.thresholds.bufferTokens = parsePositiveIntSetting(key, value);
+  else if (["buffer-activation", "activation-ratio"].includes(normalized)) state.thresholds.bufferActivation = parseRatioSetting(key, value);
+  else if (["observation-model", "observer-model", "observe-model"].includes(normalized)) state.settings.observationModel = value.trim();
+  else if (["reflection-model", "reflector-model", "reflect-model"].includes(normalized)) state.settings.reflectionModel = value.trim();
+  else if (normalized === "caveman") state.settings.caveman = parseBooleanSetting(key, value);
+  else if (["attachments", "observe-attachments", "attachment-observation"].includes(normalized)) state.settings.observeAttachments = parseAttachmentSetting(key, value);
+  else if (["retrieval", "retrieval-provider", "vector-provider"].includes(normalized)) {
+    state.settings.retrieval.provider = parseRetrievalProvider(key, value);
+    if (state.settings.retrieval.provider === "gemini" && state.settings.retrieval.model === "local/hash-bow-v1") state.settings.retrieval.model = "gemini-embedding-001";
+    if (state.settings.retrieval.provider === "local" && state.settings.retrieval.model === "gemini-embedding-001") state.settings.retrieval.model = "local/hash-bow-v1";
+    state.vectorIndex = undefined;
+  }
+  else if (["retrieval-model", "embedding-model", "vector-model"].includes(normalized)) { state.settings.retrieval.model = value.trim(); state.vectorIndex = undefined; }
+  else if (["retrieval-top-k", "top-k", "vector-top-k"].includes(normalized)) state.settings.retrieval.topK = clampInt(parsePositiveIntSetting(key, value), 1, 30);
+  else if (["retrieval-threshold", "vector-threshold"].includes(normalized)) state.settings.retrieval.threshold = parseRatioSetting(key, value);
+  else if (normalized === "scope") {
+    const scope = value.trim().toLowerCase();
+    if (scope !== "session" && scope !== "project") throw new Error("OM scope must be session or project");
+    if (state.scope !== scope) state.vectorIndex = undefined;
+    state.scope = scope;
+  } else {
+    throw new Error(`Unknown OM setting: ${key}`);
+  }
+  if (state.thresholds.blockAfter < state.thresholds.observation) state.thresholds.blockAfter = Math.round(state.thresholds.observation * DEFAULT_BLOCK_AFTER_MULTIPLIER);
+  state.observationTokens = estimateTokens(state.observations);
+}
+
+function formatSettingsText(state: PiOMRecord): string {
+  return [
+    formatDetailedStatus(state),
+    "",
+    "settings:",
+    `  observation-model: ${state.settings.observationModel}`,
+    `  reflection-model: ${state.settings.reflectionModel}`,
+    `  caveman: ${state.settings.caveman ? "on" : "off"}`,
+    `  attachments: ${state.settings.observeAttachments}`,
+    `  scope: ${state.scope}`,
+    `  retrieval: ${state.settings.retrieval.provider}`,
+    `  retrieval-model: ${state.settings.retrieval.model}`,
+    `  retrieval-top-k: ${state.settings.retrieval.topK}`,
+    `  retrieval-threshold: ${state.settings.retrieval.threshold}`,
+    `  vector-index: ${state.vectorIndex ? `${state.vectorIndex.entries.length} entries (${state.vectorIndex.provider}/${state.vectorIndex.model})` : "none"}`,
+    "",
+    "usage:",
+    "  /om set observation-threshold 30000",
+    "  /om set reflection-threshold 40000",
+    "  /om set observation-model google/gemini-2.5-flash",
+    "  /om set caveman on",
+    "  /om set retrieval local",
+    "  /om vector status|rebuild|search <query>",
+    "  /om reset",
+  ].join("\n");
+}
+
 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"}`;
 }
@@ -1402,7 +2311,7 @@ async function writeDebug(ctx: any, name: string, payload: unknown): Promise<voi
     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");
+    await writeFile(file, JSON.stringify(redactDeep({ extension: EXTENSION_ID, sessionId: state.sessionId, ...payload as any }), null, 2) + "\n", "utf8");
   } catch (error) {
     // Ignore debug write errors if context is stale
   }
@@ -1427,6 +2336,30 @@ function mergeAbortSignals(a?: AbortSignal, b?: AbortSignal): AbortSignal | unde
   return controller.signal;
 }
 
+export const __test = {
+  redactSecrets,
+  redactDeep,
+  limitTextByTokens,
+  buildObserverTaskPrompt,
+  defaultSettings,
+  defaultThresholds,
+  createDefaultState,
+  normalizeState,
+  isStaleOperationLock,
+  recoverStaleOperationLock,
+  atomicWriteJson,
+  applySetting,
+  formatSettingsText,
+  suppressDuplicateObservations,
+  buildLocalVectorIndex,
+  retrieveRelevantObservations,
+  buildObserverInput,
+  modelSupportsAttachments,
+  formatVectorStatus,
+  shouldObserveAttachment,
+  geminiEmbedding,
+};
+
 class OMOverlay {
   private scroll = 0;
   private tab: "memory" | "status" | "debug" = "memory";