pi-observational-memory 0.1.7 → 1.0.1

package/README.md

@@ -1,35 +1,100 @@
 # pi-observational-memory
 
-Observational memory extension for [Pi](https://github.com/mariozechner/pi). Replaces Pi's default compaction with a two-tier system of **observations** (timestamped event log) and **reflections** (stable long-term facts), giving the agent persistent memory across long conversations.
+**Make Pi sessions feel endless.**
 
-Inspired by [Mastra's Observational Memory](https://mastra.ai/blog/observational-memory#how-it-works) concept. This is an independent implementation adapted for Pi's extension system and compaction model.
+Every session has a cliff. You're three hours in, the context window fills up, compaction runs, and suddenly the agent doesn't remember what you decided in hour one. You start repeating yourself. The session that was flowing now feels like a new conversation with an amnesiac.
+
+pi-observational-memory pushes that cliff out far enough that you stop thinking about it. It replaces Pi's compaction summary with a two-tier memory system — **observations** (a timestamped, priority-tagged event log) and **reflections** (stable long-term facts) — so the agent carries forward *what* you decided, *when*, *why*, and what's already done. Not as prose that degrades with each compaction cycle, but as structured memory that stays sharp.
+
+```
+<reflections>
+- User works at Acme Corp, building "Acme Dashboard"
+- Stack: Next.js 15, Supabase auth, server components with client-side hydration
+- Hard constraint: ship by January 22nd 2026
+</reflections>
+
+<observations>
+Date: 2026-01-15
+- 🔴 14:30 User decided to switch from REST to GraphQL for the public API
+  - 🟡 14:32 Motivation: reduce over-fetching on mobile clients
+- 🟢 14:35 Agent scaffolded GraphQL schema in src/schema.ts
+- ✅ 14:50 GraphQL migration completed — user confirmed queries working
+- 🔴 15:10 User wants rate limiting on all public endpoints
+  - 🟡 15:12 Prefers token bucket algorithm, 100 req/min per API key
+</observations>
+```
+
+Hour six should feel like hour one. The agent knows who you are, what you've built together, and what's left to do.
+
+Pi's built-in compaction handles most sessions well — it tracks file operations, manages split turns, and keeps recent messages intact. This extension is for the sessions where "most" isn't enough: long builds, multi-feature sprints, and the kind of deep work where breaking flow to start a new session costs you more than the tokens.
+
+Inspired by [Mastra's Observational Memory](https://mastra.ai/blog/observational-memory) research (94.87% on LongMemEval). This is an independent implementation built for Pi's extension system and compaction model.
+
+## Why this matters
+
+Pi's default compaction summarizes old messages into prose and tracks which files were read and modified. This works well for short-to-medium sessions. But prose summaries are inherently lossy in ways that compound over time — the third compaction summarizes a summary of a summary, and specific decisions, timestamps, and completion states get flattened.
+
+Observational memory uses a different format that's designed to survive repeated compaction cycles:
+
+| What you get | Why it matters |
+|---|---|
+| 🔴 Priority tags | Agent knows what's important vs. what's noise |
+| Timestamps | Temporal reasoning — agent knows *when* things happened |
+| ✅ Completion markers | Agent won't redo finished work |
+| State change tracking | "Switched from A to B" — no stale decisions |
+| User quotes preserved | Your exact words survive compression |
+| Reflections tier | Identity and constraints never get pruned |
 
 ## How it works
 
-When Pi's context window fills up, this extension intercepts the compaction event and runs two LLM passes:
+Two LLM passes intercept Pi's compaction to produce structured output instead of prose:
+
+```
+Raw messages accumulate
+        │
+        ▼  exceeds observationThreshold (default: 50k tokens)
+   ┌─────────┐
+   │ Observer │──▶ Compresses messages into timestamped,
+   └─────────┘    priority-tagged observations. Append-only.
+        │
+        ▼  observations exceed reflectionThreshold (default: 30k tokens)
+  ┌───────────┐
+  │ Reflector │──▶ Promotes stable facts to reflections.
+  └───────────┘    Prunes only what it's certain is dead.
+        │
+        ▼
+  ┌──────────────────────────────┐
+  │ Agent context:               │
+  │  1. System prompt            │
+  │  2. Reflections (stable)     │
+  │  3. Observations (event log) │
+  │  4. Recent raw messages      │
+  └──────────────────────────────┘
+```
 
-1. **Observer** — reads recent conversation messages and compresses them into concise, timestamped observations with priority levels (🔴 important, 🟡 maybe important, 🟢 info, ✅ completed).
-2. **Reflector** — when observations grow past a threshold, promotes stable facts to reflections and prunes dead observations.
+The observer is aggressive — it compresses everything into dense observations. The reflector is conservative — it only prunes what's clearly dead. Between reflector runs, no information is lost.
 
-The resulting `<reflections>` + `<observations>` block becomes the compaction summary that Pi injects at the top of the agent's context. Pi still keeps the most recent raw messages (controlled by `keepRecentTokens`), so the agent sees both structured memory and recent conversation.
+For the full technical breakdown — compaction lifecycle, state persistence, configuration interactions — see **[docs/how-it-works.md](docs/how-it-works.md)**.
 
 ## Install
 
 ```bash
-npm install pi-observational-memory
+pi install npm:pi-observational-memory
 ```
 
-Then symlink or copy the package into Pi's extensions directory:
+Or from GitHub:
 
 ```bash
-ln -s $(npm root)/pi-observational-memory ~/.pi/extensions/pi-observational-memory
+pi install git:github.com/elpapi42/pi-observational-memory
 ```
 
-Pi will discover it on next session start.
+That's it. The extension hooks into Pi's compaction lifecycle automatically. No config file needed to start — defaults work well for most sessions.
 
 ## Configuration
 
-Create `~/.pi/agent/observational-memory.json`:
+### Extension settings
+
+Create `~/.pi/agent/observational-memory.json` (or `.pi/observational-memory.json` per project):
 
 ```json
 {
@@ -38,29 +103,60 @@ Create `~/.pi/agent/observational-memory.json`:
 }
 ```
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `observationThreshold` | `50000` | Token count that triggers the observer |
-| `reflectionThreshold` | `30000` | Observation token count that triggers the reflector |
-| `compactionModel` | session model | Optional `{ "provider": "...", "id": "..." }` to use a different model for observation/reflection |
+| Setting | Default | What it controls |
+|---|---|---|
+| `observationThreshold` | `50,000` tokens | How much raw conversation accumulates before the observer runs |
+| `reflectionThreshold` | `30,000` tokens | How large observations grow before the reflector promotes and prunes |
+| `compactionModel` | session model | Optional — use a cheaper model for observer/reflector passes |
+
+### Using a cheaper model for compaction
 
-### Custom model example
+The observer and reflector don't need the same capabilities as your coding agent. Offload them to something fast and cheap:
 
 ```json
 {
-  "observationThreshold": 6000,
-  "reflectionThreshold": 1000,
   "compactionModel": { "provider": "openrouter", "id": "google/gemma-4-31b-it" }
 }
 ```
 
+### Pi compaction settings
+
+The extension works with Pi's built-in compaction settings in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "compaction": {
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+| Setting | Default | What it controls |
+|---|---|---|
+| `keepRecentTokens` | `20,000` | Tokens of recent conversation kept verbatim (not summarized) |
+| `reserveTokens` | `16,384` | Headroom for LLM response; Pi auto-compacts when context exceeds `window - reserveTokens` |
+
+**How they interact:** Pi decides *when* to compact and *how many recent messages to keep raw*. The extension decides *how* to compact (observations + reflections instead of a flat summary) and *when to proactively trigger* compaction before the window fills. Both paths end up at the same `session_before_compact` hook.
+
 ## Commands
 
 | Command | Description |
-|---------|-------------|
-| `/om-status` | Show token counts and current thresholds |
+|---|---|
+| `/om-status` | Token counts, thresholds, and when the next observer/reflector pass will trigger |
 | `/om-view` | Print current reflections and observations |
-| `/om-view --full` | Same as above, plus raw kept messages |
+| `/om-view --full` | Same as above, plus the raw kept messages |
+
+## Design decisions
+
+**Why observations are append-only.** Between reflector runs, nothing is lost. The observer only compresses new messages — it doesn't decide what to keep. This keeps the observer simple and predictable.
+
+**Why the reflector is conservative.** It only prunes what it's certain is dead: completed tasks no longer referenced, superseded information, exact duplicates. Being old or low-priority is not a reason to prune. If in doubt, it keeps.
+
+**Why user messages are captured near-verbatim.** When the context window shrinks, observations become the only record of what you said. Short messages are preserved exactly; long ones are summarized with key phrases quoted.
+
+**Why state changes are explicit.** When you say "switching from A to B," the observation notes both the new state and what it replaces. This prevents the agent from acting on stale information after compaction.
+
+**Why memory lives in the session.** State is stored in Pi's session entries as compaction `details` — no external database, no filesystem state, no separate sync. On session resume, the extension walks backward through entries to restore memory. If you use `/tree` to branch, each branch gets its own memory state.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-observational-memory",
-  "version": "0.1.7",
+  "version": "1.0.1",
   "description": "Observational memory extension for pi — cache-friendly tiered compaction with observations and reflections.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+export interface Config {
+	observationThreshold: number;
+	reflectionThreshold: number;
+	compactionModel?: { provider: string; id: string };
+}
+
+export const DEFAULTS: Config = {
+	observationThreshold: 50_000,
+	reflectionThreshold: 30_000,
+};
+
+export function loadConfig(cwd: string): Config {
+	const globalPath = join(getAgentDir(), "observational-memory.json");
+	const projectPath = join(cwd, ".pi", "observational-memory.json");
+
+	let globalConfig: Partial<Config> = {};
+	let projectConfig: Partial<Config> = {};
+
+	if (existsSync(globalPath)) {
+		try {
+			globalConfig = JSON.parse(readFileSync(globalPath, "utf-8"));
+		} catch {}
+	}
+
+	if (existsSync(projectPath)) {
+		try {
+			projectConfig = JSON.parse(readFileSync(projectPath, "utf-8"));
+		} catch {}
+	}
+
+	return { ...DEFAULTS, ...globalConfig, ...projectConfig };
+}

package/src/index.ts

@@ -1,312 +1,18 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { completeSimple } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import {
-	convertToLlm,
-	estimateTokens as estimateMessageTokens,
-	getAgentDir,
-	serializeConversation,
-} from "@mariozechner/pi-coding-agent";
-
-// ============================================================================
-// Config
-// ============================================================================
-
-interface Config {
-	observationThreshold: number;
-	reflectionThreshold: number;
-	compactionModel?: { provider: string; id: string };
-}
-
-const DEFAULTS: Config = {
-	observationThreshold: 50_000,
-	reflectionThreshold: 30_000,
-};
-
-function loadConfig(cwd: string): Config {
-	const globalPath = join(getAgentDir(), "observational-memory.json");
-	const projectPath = join(cwd, ".pi", "observational-memory.json");
-
-	let globalConfig: Partial<Config> = {};
-	let projectConfig: Partial<Config> = {};
-
-	if (existsSync(globalPath)) {
-		try {
-			globalConfig = JSON.parse(readFileSync(globalPath, "utf-8"));
-		} catch {}
-	}
-
-	if (existsSync(projectPath)) {
-		try {
-			projectConfig = JSON.parse(readFileSync(projectPath, "utf-8"));
-		} catch {}
-	}
-
-	return { ...DEFAULTS, ...globalConfig, ...projectConfig };
-}
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface MemoryState {
-	observations: string;
-	reflections: string;
-}
-
-interface MemoryDetails {
-	type: "observational-memory";
-	version: 1;
-	observations: string;
-	reflections: string;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function isMemoryDetails(d: unknown): d is MemoryDetails {
-	return !!d && typeof d === "object" && (d as Record<string, unknown>).type === "observational-memory";
-}
-
-function estimateTokens(text: string): number {
-	return Math.ceil(text.length / 4);
-}
-
-function estimateRawTailTokens(
-	entries: Array<{ type: string; message?: unknown; content?: unknown; firstKeptEntryId?: string; id?: string }>,
-): number {
-	let startIndex = 0;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		if (entries[i].type === "compaction") {
-			const keptId = entries[i].firstKeptEntryId;
-			if (keptId) {
-				for (let j = 0; j < entries.length; j++) {
-					if (entries[j].id === keptId) {
-						startIndex = j;
-						break;
-					}
-				}
-			} else {
-				startIndex = i + 1;
-			}
-			break;
-		}
-	}
-
-	let tokens = 0;
-	for (let i = startIndex; i < entries.length; i++) {
-		const entry = entries[i];
-		if (entry.type === "message" && entry.message) {
-			tokens += estimateMessageTokens(entry.message as Parameters<typeof estimateMessageTokens>[0]);
-		} else if (entry.type === "custom_message" && entry.content) {
-			const content = entry.content;
-			if (typeof content === "string") {
-				tokens += Math.ceil(content.length / 4);
-			} else if (Array.isArray(content)) {
-				for (const block of content) {
-					if (block.type === "text" && block.text) tokens += Math.ceil(block.text.length / 4);
-				}
-			}
-		}
-	}
-	return tokens;
-}
-
-function extractText(response: { content: Array<{ type: string; text?: string }> }): string {
-	return response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map((c) => c.text)
-		.join("\n");
-}
-
-// ============================================================================
-// Prompts
-// ============================================================================
-
-const OBSERVER_SYSTEM = `You are an observation agent for a coding assistant. Compress conversation messages into concise, timestamped observations.
-
-Format as a date-grouped log:
-
-Date: YYYY-MM-DD
-- 🔴 HH:MM Observation text
-  - 🔴 HH:MM Sub-observation
-  - 🟡 HH:MM Sub-observation
-- 🟢 HH:MM Another observation
-
-Priority levels:
-- 🔴 Important: user goals, constraints, decisions, names, deadlines, architectural choices, bugs, errors
-- 🟡 Maybe important: questions asked, preferences, approaches considered, configuration details
-- 🟢 Info only: routine operations, minor details
-- ✅ Completed: a task, question, subtask, or issue is concretely resolved
-
-CRITICAL — DISTINGUISH USER ASSERTIONS FROM QUESTIONS:
-
-When the user TELLS you something about themselves, mark it as an assertion:
-- "I have two kids" → 🔴 User stated has two kids
-- "I work at Acme Corp" → 🔴 User stated works at Acme Corp
-
-When the user ASKS about something, mark it as a question/request:
-- "Can you help me with X?" → 🔴 User asked help with X
-- "What's the best way to do Y?" → 🟡 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 date if mentioned)")
-- "I need to do X" → Statement of intent (extract as "User stated they need to do X")
-
-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.
-
-Rules:
-- Group observations by date, with timestamps inline.
-- Use the three-date model when relevant: note the observation date, the referenced date (if the event refers to a different day), and a relative date (e.g. "2 days ago").
-- Nest related sub-observations under a parent observation.
-- Preserve exact file paths, function names, error messages, and technical details.
-- Focus on WHAT happened and WHY, not routine tool calls.
-- Each observation should be one concise line.
-
-CONTENT PRESERVATION:
-
-User message capture:
-- Short and medium-length user messages: capture nearly verbatim.
-- Very long user messages: summarize but quote key phrases that carry specific intent or meaning.
-- This is critical — when the conversation window shrinks, observations are the only record of what the user said.
-
-Preserve unusual phrasing — quote the user's exact words when non-standard:
-- BAD: User exercised.
-- GOOD: User stated they did a "movement session" (their term for exercise).
-
-Use precise action verbs — replace vague verbs with specific ones:
-- BAD: User is getting X.
-- GOOD: User subscribed to X. (if context confirms recurring delivery)
-- GOOD: User purchased X. (if context confirms one-time acquisition)
-Common: "getting regularly" → "subscribed to"; "got" → "purchased"/"received"/"was given"; "stopped getting" → "canceled"/"unsubscribed from"
-If the assistant confirms or clarifies the user's vague language, prefer the assistant's more precise terminology.
-
-Preserve distinguishing details in assistant-generated content:
-- BAD: Assistant recommended 5 hotels.
-- GOOD: Assistant recommended hotels: Hotel A (near station), Hotel B (budget-friendly), Hotel C (rooftop pool).
-- BAD: Assistant provided social media accounts.
-- GOOD: Assistant provided accounts: @user_one (portraits), @user_two (landscapes).
-
-Preserve specific technical/numerical values:
-- BAD: Assistant explained the performance improvements.
-- GOOD: Optimization achieved 43.7% faster load times, memory dropped from 2.8GB to 940MB.
-
-Preserve role/participation when user mentions their involvement:
-- BAD: User attended the company event.
-- GOOD: User was a presenter at the company event.
-
-Code context — always preserve: exact file paths with line numbers, error messages verbatim, function/variable names, architectural decisions and rationale.
-
-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 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).
-- Do NOT repeat information already captured in existing reflections or observations.
-- Do NOT wrap output in code blocks or markdown fences.
-
-AVOIDING REPETITIVE OBSERVATIONS:
-- Do NOT repeat the same observation across multiple turns if there is no new information.
-- When the agent performs repeated similar actions (e.g., browsing files, running the same tool type multiple times), group them into a single parent observation with sub-bullets for each new result.
-
-BAD (repetitive):
-- 🟡 14:30 Agent used view tool on src/auth.ts
-- 🟡 14:31 Agent used view tool on src/users.ts
-- 🟡 14:32 Agent used view tool on src/routes.ts
-
-GOOD (grouped):
-- 🟡 14:30 Agent investigated auth flow
-  - -> viewed src/auth.ts — found token validation logic
-  - -> viewed src/users.ts — found user lookup by email
-  - -> viewed src/routes.ts — found middleware chain
-
-Only add a new observation for a repeated action if the NEW result changes the picture.
-
-COMPLETION TRACKING:
-✅ markers are explicit memory signals telling the assistant that work is finished and should not be repeated.
-
-Use ✅ when:
-- The user explicitly confirms something worked ("thanks, that fixed it", "got it", "perfect")
-- The assistant provided a definitive answer and the user moved on
-- A multi-step task reached its stated goal
-- The user acknowledged receipt of requested information
-- A concrete subtask or implementation step completed during ongoing work
-
-Do NOT use ✅ when:
-- The assistant merely responded — the user might follow up with corrections
-- The topic is paused but not resolved ("I'll try that later")
-- The user's reaction is ambiguous
-
-Two formats:
-As a sub-bullet under a parent observation:
-- 🔴 HH:MM User asked how to configure auth middleware
-  - -> Agent explained JWT setup with code example
-  - ✅ User confirmed auth is working
-
-Or standalone when closing a broader task:
-- ✅ HH:MM Auth configuration completed — user confirmed middleware is working
-
-Completion observations should be terse but specific about WHAT was completed. Prefer concrete resolved outcomes over abstract workflow status.`;
-
-const REFLECTOR_SYSTEM = `You are a reflection agent for a coding assistant. Your job is to maintain long-term reflections while preserving as many observations as possible.
-
-You will receive current reflections (long-term facts) and accumulated observations.
-
-Your task:
-1. PROMOTE observations to reflections ONLY when they are clearly stable, long-lived facts:
-   - User identity, role, preferences
-   - Project goals and architecture decisions
-   - Permanent constraints and requirements
-   - Key technical decisions and their rationale
-   After promoting, KEEP the original observation — do not remove it.
-2. PRUNE observations ONLY when you are certain they are dead:
-   - Tasks explicitly completed AND no longer referenced
-   - Information directly contradicted or superseded by a newer observation
-   - Exact duplicates of other observations
-   When in doubt, KEEP the observation.
-   IMPORTANT: Preserve ✅ completion markers — they tell the assistant what is already resolved and prevent repeated work. Preserve the concrete resolved outcome captured by ✅ markers. When pruning detailed steps of a completed task, keep the ✅ outcome line.
-   USER ASSERTIONS vs QUESTIONS: "User stated: X" = authoritative assertion. "User asked: X" = question/request. When consolidating, USER ASSERTIONS TAKE PRECEDENCE. If you see both "User stated: has two kids" and later "User asked: how many kids?", keep the assertion — the question doesn't invalidate what they told you.
-3. KEEP everything else. Most observations should survive. An observation being old or low-priority (🟢) is NOT a reason to remove it.
-4. UPDATE reflections: merge new promoted facts into existing reflections. Remove reflections only if directly contradicted by observations.
-
-Output EXACTLY two sections with these tags:
-
-<reflections>
-[Updated long-term reflections — stable facts, one per line]
-</reflections>
-
-<observations>
-[Surviving observations in the same date-grouped log format — most should be preserved]
-</observations>
-
-Do NOT wrap output in code blocks or markdown fences.`;
-
-const CONTEXT_USAGE_INSTRUCTIONS = `KNOWLEDGE UPDATES: When observations contain conflicting information, prefer the MOST RECENT observation (check dates). Look for state-change phrases like "will start", "is switching", "changed to", "replacing" as indicators that older information has been superseded.
-
-PLANNED ACTIONS: If an observation says the user planned to do something and the date is now in the past, assume they completed the action unless there's evidence they didn't.
-
-USER ASSERTIONS: When observations contain both "User stated: X" and "User asked: X" about the same topic, the assertion is authoritative — the user is the source of truth about their own life.
-
-COMPLETION MARKERS: Observations marked with ✅ indicate completed work. Do not re-do or re-investigate tasks marked as complete unless the user explicitly asks to revisit them.`;
-
-// ============================================================================
-// Extension
-// ============================================================================
+import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+import { DEFAULTS, loadConfig } from "./config.js";
+import type { Config } from "./config.js";
+import { CONTEXT_USAGE_INSTRUCTIONS, OBSERVER_SYSTEM, REFLECTOR_SYSTEM } from "./prompts.js";
+import { estimateRawTailTokens, estimateTokens, extractText } from "./tokens.js";
+import type { MemoryDetails, MemoryState } from "./types.js";
+import { isMemoryDetails } from "./types.js";
 
 export default function observationalMemory(pi: ExtensionAPI) {
 	let config: Config = { ...DEFAULTS };
 	let state: MemoryState = { observations: "", reflections: "" };
 	let compactInFlight = false;
 
-	// ---- Restore state from last compaction entry ----
-
 	pi.on("session_start", (_event, ctx) => {
 		config = loadConfig(ctx.cwd);
 		state = { observations: "", reflections: "" };
@@ -323,8 +29,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 		}
 	});
 
-	// ---- Trigger compaction when raw tail exceeds threshold ----
-
 	pi.on("agent_end", (_event, ctx) => {
 		if (compactInFlight) return;
 
@@ -351,8 +55,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 		}, 0);
 	});
 
-	// ---- Custom compaction: observer + reflector ----
-
 	pi.on("session_before_compact", async (event, ctx) => {
 		const { preparation, signal } = event;
 		const { messagesToSummarize, turnPrefixMessages, firstKeptEntryId, tokensBefore } = preparation;
@@ -382,8 +84,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 		const dateStr = now.toISOString().split("T")[0];
 		const timeStr = now.toTimeString().slice(0, 5);
 
-		// ---- Run observer ----
-
 		ctx.ui.notify("Observational memory: running observer...", "info");
 
 		try {
@@ -423,8 +123,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 			return;
 		}
 
-		// ---- Run reflector if observations are too large ----
-
 		if (estimateTokens(state.observations) > config.reflectionThreshold) {
 			ctx.ui.notify("Observational memory: running reflector...", "info");
 
@@ -465,8 +163,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 			}
 		}
 
-		// ---- Build summary ----
-
 		let summary = "";
 		if (state.reflections) {
 			summary += `<reflections>\n${state.reflections}\n</reflections>\n\n`;
@@ -496,8 +192,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 		};
 	});
 
-	// ---- /om-status command ----
-
 	pi.registerCommand("om-status", {
 		description: "Show observational memory status",
 		handler: async (_args, ctx) => {
@@ -521,8 +215,6 @@ export default function observationalMemory(pi: ExtensionAPI) {
 		},
 	});
 
-	// ---- /om-view command ----
-
 	pi.registerCommand("om-view", {
 		description: "Print full observational memory contents (--full to include raw messages)",
 		handler: async (args, ctx) => {

package/src/prompts.ts

@@ -0,0 +1,170 @@
+export const OBSERVER_SYSTEM = `You are an observation agent for a coding assistant. Compress conversation messages into concise, timestamped observations.
+
+Format as a date-grouped log:
+
+Date: YYYY-MM-DD
+- 🔴 HH:MM Observation text
+  - 🔴 HH:MM Sub-observation
+  - 🟡 HH:MM Sub-observation
+- 🟢 HH:MM Another observation
+
+Priority levels:
+- 🔴 Important: user goals, constraints, decisions, names, deadlines, architectural choices, bugs, errors
+- 🟡 Maybe important: questions asked, preferences, approaches considered, configuration details
+- 🟢 Info only: routine operations, minor details
+- ✅ Completed: a task, question, subtask, or issue is concretely resolved
+
+CRITICAL — DISTINGUISH USER ASSERTIONS FROM QUESTIONS:
+
+When the user TELLS you something about themselves, mark it as an assertion:
+- "I have two kids" → 🔴 User stated has two kids
+- "I work at Acme Corp" → 🔴 User stated works at Acme Corp
+
+When the user ASKS about something, mark it as a question/request:
+- "Can you help me with X?" → 🔴 User asked help with X
+- "What's the best way to do Y?" → 🟡 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 date if mentioned)")
+- "I need to do X" → Statement of intent (extract as "User stated they need to do X")
+
+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.
+
+Rules:
+- Group observations by date, with timestamps inline.
+- Use the three-date model when relevant: note the observation date, the referenced date (if the event refers to a different day), and a relative date (e.g. "2 days ago").
+- Nest related sub-observations under a parent observation.
+- Preserve exact file paths, function names, error messages, and technical details.
+- Focus on WHAT happened and WHY, not routine tool calls.
+- Each observation should be one concise line.
+
+CONTENT PRESERVATION:
+
+User message capture:
+- Short and medium-length user messages: capture nearly verbatim.
+- Very long user messages: summarize but quote key phrases that carry specific intent or meaning.
+- This is critical — when the conversation window shrinks, observations are the only record of what the user said.
+
+Preserve unusual phrasing — quote the user's exact words when non-standard:
+- BAD: User exercised.
+- GOOD: User stated they did a "movement session" (their term for exercise).
+
+Use precise action verbs — replace vague verbs with specific ones:
+- BAD: User is getting X.
+- GOOD: User subscribed to X. (if context confirms recurring delivery)
+- GOOD: User purchased X. (if context confirms one-time acquisition)
+Common: "getting regularly" → "subscribed to"; "got" → "purchased"/"received"/"was given"; "stopped getting" → "canceled"/"unsubscribed from"
+If the assistant confirms or clarifies the user's vague language, prefer the assistant's more precise terminology.
+
+Preserve distinguishing details in assistant-generated content:
+- BAD: Assistant recommended 5 hotels.
+- GOOD: Assistant recommended hotels: Hotel A (near station), Hotel B (budget-friendly), Hotel C (rooftop pool).
+- BAD: Assistant provided social media accounts.
+- GOOD: Assistant provided accounts: @user_one (portraits), @user_two (landscapes).
+
+Preserve specific technical/numerical values:
+- BAD: Assistant explained the performance improvements.
+- GOOD: Optimization achieved 43.7% faster load times, memory dropped from 2.8GB to 940MB.
+
+Preserve role/participation when user mentions their involvement:
+- BAD: User attended the company event.
+- GOOD: User was a presenter at the company event.
+
+Code context — always preserve: exact file paths with line numbers, error messages verbatim, function/variable names, architectural decisions and rationale.
+
+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 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).
+- Do NOT repeat information already captured in existing reflections or observations.
+- Do NOT wrap output in code blocks or markdown fences.
+
+AVOIDING REPETITIVE OBSERVATIONS:
+- Do NOT repeat the same observation across multiple turns if there is no new information.
+- When the agent performs repeated similar actions (e.g., browsing files, running the same tool type multiple times), group them into a single parent observation with sub-bullets for each new result.
+
+BAD (repetitive):
+- 🟡 14:30 Agent used view tool on src/auth.ts
+- 🟡 14:31 Agent used view tool on src/users.ts
+- 🟡 14:32 Agent used view tool on src/routes.ts
+
+GOOD (grouped):
+- 🟡 14:30 Agent investigated auth flow
+  - -> viewed src/auth.ts — found token validation logic
+  - -> viewed src/users.ts — found user lookup by email
+  - -> viewed src/routes.ts — found middleware chain
+
+Only add a new observation for a repeated action if the NEW result changes the picture.
+
+COMPLETION TRACKING:
+✅ markers are explicit memory signals telling the assistant that work is finished and should not be repeated.
+
+Use ✅ when:
+- The user explicitly confirms something worked ("thanks, that fixed it", "got it", "perfect")
+- The assistant provided a definitive answer and the user moved on
+- A multi-step task reached its stated goal
+- The user acknowledged receipt of requested information
+- A concrete subtask or implementation step completed during ongoing work
+
+Do NOT use ✅ when:
+- The assistant merely responded — the user might follow up with corrections
+- The topic is paused but not resolved ("I'll try that later")
+- The user's reaction is ambiguous
+
+Two formats:
+As a sub-bullet under a parent observation:
+- 🔴 HH:MM User asked how to configure auth middleware
+  - -> Agent explained JWT setup with code example
+  - ✅ User confirmed auth is working
+
+Or standalone when closing a broader task:
+- ✅ HH:MM Auth configuration completed — user confirmed middleware is working
+
+Completion observations should be terse but specific about WHAT was completed. Prefer concrete resolved outcomes over abstract workflow status.`;
+
+export const REFLECTOR_SYSTEM = `You are a reflection agent for a coding assistant. Your job is to maintain long-term reflections while preserving as many observations as possible.
+
+You will receive current reflections (long-term facts) and accumulated observations.
+
+Your task:
+1. PROMOTE observations to reflections ONLY when they are clearly stable, long-lived facts:
+   - User identity, role, preferences
+   - Project goals and architecture decisions
+   - Permanent constraints and requirements
+   - Key technical decisions and their rationale
+   After promoting, KEEP the original observation — do not remove it.
+2. PRUNE observations ONLY when you are certain they are dead:
+   - Tasks explicitly completed AND no longer referenced
+   - Information directly contradicted or superseded by a newer observation
+   - Exact duplicates of other observations
+   When in doubt, KEEP the observation.
+   IMPORTANT: Preserve ✅ completion markers — they tell the assistant what is already resolved and prevent repeated work. Preserve the concrete resolved outcome captured by ✅ markers. When pruning detailed steps of a completed task, keep the ✅ outcome line.
+   USER ASSERTIONS vs QUESTIONS: "User stated: X" = authoritative assertion. "User asked: X" = question/request. When consolidating, USER ASSERTIONS TAKE PRECEDENCE. If you see both "User stated: has two kids" and later "User asked: how many kids?", keep the assertion — the question doesn't invalidate what they told you.
+3. KEEP everything else. Most observations should survive. An observation being old or low-priority (🟢) is NOT a reason to remove it.
+4. UPDATE reflections: merge new promoted facts into existing reflections. Remove reflections only if directly contradicted by observations.
+
+Output EXACTLY two sections with these tags:
+
+<reflections>
+[Updated long-term reflections — stable facts, one per line]
+</reflections>
+
+<observations>
+[Surviving observations in the same date-grouped log format — most should be preserved]
+</observations>
+
+Do NOT wrap output in code blocks or markdown fences.`;
+
+export const CONTEXT_USAGE_INSTRUCTIONS = `KNOWLEDGE UPDATES: When observations contain conflicting information, prefer the MOST RECENT observation (check dates). Look for state-change phrases like "will start", "is switching", "changed to", "replacing" as indicators that older information has been superseded.
+
+PLANNED ACTIONS: If an observation says the user planned to do something and the date is now in the past, assume they completed the action unless there's evidence they didn't.
+
+USER ASSERTIONS: When observations contain both "User stated: X" and "User asked: X" about the same topic, the assertion is authoritative — the user is the source of truth about their own life.
+
+COMPLETION MARKERS: Observations marked with ✅ indicate completed work. Do not re-do or re-investigate tasks marked as complete unless the user explicitly asks to revisit them.`;

package/src/tokens.ts

@@ -0,0 +1,52 @@
+import { estimateTokens as estimateMessageTokens } from "@mariozechner/pi-coding-agent";
+
+export function estimateTokens(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+export function estimateRawTailTokens(
+	entries: Array<{ type: string; message?: unknown; content?: unknown; firstKeptEntryId?: string; id?: string }>,
+): number {
+	let startIndex = 0;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].type === "compaction") {
+			const keptId = entries[i].firstKeptEntryId;
+			if (keptId) {
+				for (let j = 0; j < entries.length; j++) {
+					if (entries[j].id === keptId) {
+						startIndex = j;
+						break;
+					}
+				}
+			} else {
+				startIndex = i + 1;
+			}
+			break;
+		}
+	}
+
+	let tokens = 0;
+	for (let i = startIndex; i < entries.length; i++) {
+		const entry = entries[i];
+		if (entry.type === "message" && entry.message) {
+			tokens += estimateMessageTokens(entry.message as Parameters<typeof estimateMessageTokens>[0]);
+		} else if (entry.type === "custom_message" && entry.content) {
+			const content = entry.content;
+			if (typeof content === "string") {
+				tokens += Math.ceil(content.length / 4);
+			} else if (Array.isArray(content)) {
+				for (const block of content) {
+					if (block.type === "text" && block.text) tokens += Math.ceil(block.text.length / 4);
+				}
+			}
+		}
+	}
+	return tokens;
+}
+
+export function extractText(response: { content: Array<{ type: string; text?: string }> }): string {
+	return response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+export interface MemoryState {
+	observations: string;
+	reflections: string;
+}
+
+export interface MemoryDetails {
+	type: "observational-memory";
+	version: 1;
+	observations: string;
+	reflections: string;
+}
+
+export function isMemoryDetails(d: unknown): d is MemoryDetails {
+	return !!d && typeof d === "object" && (d as Record<string, unknown>).type === "observational-memory";
+}