pi-observational-memory 1.0.3 → 2.1.0

package/README.md

@@ -1,80 +1,54 @@
 # pi-observational-memory
 
-**Make Pi sessions feel endless.**
+> **Make long sessions feel endless.** A Pi extension that keeps your agent in hour six knowing what you decided in hour one.
 
-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.
+## The cliff
 
-```
-<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>
-```
+Every long AI session has a cliff.
 
-Hour six should feel like hour one. The agent knows who you are, what you've built together, and what's left to do.
+You're three hours in. The context window fills up. Compaction runs. 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'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.
+Worse, compaction often hits *mid-work* — right when you were about to ask the next question. Whatever the summary captured (and didn't) becomes what the agent knows from now on.
 
-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.
+This is a universal problem for AI agents. Context windows are finite, sessions aren't, and the bridge between the two is fragile. Compactions are necessary, but they're also where memory degrades — the more you do, the further you drift from what was actually said and decided early in the session.
 
-## Why this matters
+## What this gives you
 
-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.
+`pi-observational-memory` runs an **observer** silently in the background while you work, summarizing the conversation in ~1k token chunks into a structured event log. When compaction runs, the extension assembles that log — plus stable long-term **reflections** crystallized from it — into the new summary.
 
-Observational memory uses a different format that's designed to survive repeated compaction cycles:
+What the agent sees after compaction looks like this:
 
-| 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 |
+```
+## Reflections
+User works at Acme Corp building Acme Dashboard on Next.js 15 with Supabase auth.
+Hard constraint: ship by January 22nd 2026.
+Public API uses GraphQL (switched from REST to reduce mobile over-fetching).
+
+## Observations
+2026-01-15 14:30 [high] User decided to switch from REST to GraphQL for the public API; motivation was reducing over-fetching on mobile clients.
+2026-01-15 14:35 [medium] Agent scaffolded GraphQL schema in src/schema.ts.
+2026-01-15 14:50 [medium] GraphQL migration completed; user confirmed queries working.
+2026-01-15 15:10 [critical] User wants rate limiting on all public endpoints; prefers token bucket algorithm at 100 req/min per API key.
+```
 
-## How it works
+Two layers of memory, two different jobs:
 
-Two LLM passes intercept Pi's compaction to produce structured output instead of prose:
+- **Reflections** are durable patterns — who you are, what you've decided, hard constraints. Plain prose, no timestamps. They crystallize once and persist across every future compaction.
+- **Observations** are timestamped events with a per-entry relevance tier (`low` / `medium` / `high` / `critical`). They're written near-real-time, then pruned over time — but never paraphrased.
 
-```
-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      │
-  └──────────────────────────────┘
-```
+Hour six should feel like hour one. The agent knows who you are, what you've built together, and what's left to do.
 
-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.
+## What you actually get from it
 
-For the full technical breakdown — compaction lifecycle, state persistence, configuration interactions — see **[docs/how-it-works.md](docs/how-it-works.md)**.
+- **Continuity that survives many compactions.** The summary is built by mechanical concatenation, not an LLM rewrite. What survives one compaction survives all of them, byte-identical — there's no compounding drift across cycles.
+- **Temporal reasoning.** Every observation carries a per-minute timestamp. The agent can reason about *when* something happened, not just *that* it happened.
+- **Relevance-aware pruning.** Four relevance tiers drive what gets dropped first when the observation pool grows. Trivia goes; user assertions, decisions, and verbatim errors stay.
+- **Reflections that crystallize.** Identity, constraints, and durable preferences settle into a separate layer that doesn't get re-paraphrased on each compaction.
+- **Predictable token cost.** Properly configured for your use case, this can save real money. The reflector + pruner only run above a configurable gate, so most compactions cost **zero LLM calls** — just bookkeeping. The observer can be pointed at a cheap fast model independently of your main coding model.
+- **Cache-friendly by design.** Memory updates are batched at compaction boundaries instead of injected into every turn, so prompt prefix caching keeps working between compactions.
+- **Fewer mid-work surprises.** The extension proactively triggers compaction when the agent is idle, and this will not affect your current work as after compaction you still keep the tail of your session intact.
 
 ## Install
 
@@ -88,79 +62,80 @@ Or from GitHub:
 pi install git:github.com/elpapi42/pi-observational-memory
 ```
 
-That's it. The extension hooks into Pi's compaction lifecycle automatically. No config file needed to start — defaults work well for most sessions.
+That's it. The extension hooks into Pi's lifecycle automatically. Defaults work well for most sessions — no config file needed to start.
 
-## Configuration
+## How it works (60-second version)
 
-### Extension settings
+Three tiers, two of them mostly asynchronous:
 
-Settings live under the `observational-memory` key in Pi's `settings.json` — globally at `~/.pi/agent/settings.json`, or per-project at `.pi/settings.json`. Project values override global.
+```mermaid
+flowchart TD
+    Conv([Conversation accumulates])
+    Obs[Observer<br/>async, fire-and-forget<br/>compresses each chunk into timestamped,<br/>relevance-tagged observations<br/>stored as silent tree entries]
+    Comp[Compaction<br/>extension-owned; merges accumulated<br/>observations with prior compaction state]
+    RP[Reflector + Pruner<br/>Reflector appends new reflections<br/>crystallized from the pool<br/>Pruner drops observations by id<br/>across up to 5 passes]
+    Sum[Summary mechanically assembled<br/>## Reflections<br/>&nbsp;&nbsp;plain prose lines<br/>## Observations<br/>&nbsp;&nbsp;YYYY-MM-DD HH:MM relevance ...<br/>Becomes the compactionSummary<br/>the agent sees on the next turn]
 
-```json
-{
-  "observational-memory": {
-    "observationThreshold": 50000,
-    "reflectionThreshold": 30000
-  }
-}
+    Conv -->|every ~1k raw tokens since last bound| Obs
+    Obs -->|every ~50k raw tokens since last compaction| Comp
+    Comp -->|observation pool ≥ 30k tokens| RP
+    RP --> Sum
+    Comp -.->|pool below gate — skip LLM calls| Sum
 ```
 
-| 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 |
+- **Observer** runs in the background as turns complete. The user never waits on it.
+- **Compaction** is owned by the extension. The summary is *mechanically concatenated* from current reflections + current observations — never an LLM rewrite. This is what eliminates the summary-of-a-summary problem.
+- **Reflector + Pruner** run as an inseparable pair, and only when there's enough material to crystallize. Below the gate, compaction does **zero LLM calls**.
 
-### Using a cheaper model for compaction
+The agent only ever sees the most recent compaction summary, packaged as a normal `compactionSummary` message. Observations and reflections are never injected into the live message stream — that would invalidate prefix caching with every observation. By batching memory updates at compaction boundaries, the prefix stays stable between compactions and prefix caching keeps working.
 
-The observer and reflector don't need the same capabilities as your coding agent. Offload them to something fast and cheap:
+For the full picture, read on:
 
-```json
-{
-  "observational-memory": {
-    "compactionModel": { "provider": "openrouter", "id": "google/gemma-4-31b-it" }
-  }
-}
-```
+- **[docs/concepts.md](docs/concepts.md)** — vocabulary and mental model. Start here if you're new.
+- **[docs/how-it-works.md](docs/how-it-works.md)** — the full lifecycle, data shapes, and async-race handling.
+- **[docs/configuration.md](docs/configuration.md)** — every setting, what it trades off, and tuning recipes.
 
-### Pi compaction settings
+## Configuration in 30 seconds
 
-The extension works alongside Pi's built-in compaction settings in the same `settings.json`:
+Settings live in Pi's `settings.json` — globally at `~/.pi/agent/settings.json` or per-project at `.pi/settings.json` (project values override global).
 
 ```json
 {
+  "observational-memory": {
+    "observationThresholdTokens": 1000,
+    "compactionThresholdTokens": 50000,
+    "reflectionThresholdTokens": 30000
+  },
   "compaction": {
     "keepRecentTokens": 20000
   }
 }
 ```
 
+The five settings most worth knowing:
+
 | 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` |
+| `observationThresholdTokens` | `1,000` | How often the observer fires in the background |
+| `compactionThresholdTokens` | `50,000` | How often the extension proactively triggers compaction |
+| `reflectionThresholdTokens` | `30,000` | The observation pool size at which reflector + pruner engage |
+| `compactionModel` | session model | Which model runs the observer / reflector / pruner — point at a cheaper one to save cost |
+| `compaction.keepRecentTokens` | `20,000` | How much recent conversation Pi keeps verbatim post-compaction (Pi setting; structural to the extension) |
 
-**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.
+For the full list and tuning recipes, see **[docs/configuration.md](docs/configuration.md)**.
+
+> **Upgrading from `pi-observational-memory@1.x`?** The config keys changed: v1's `observationThreshold` is now `compactionThresholdTokens`, v1's `reflectionThreshold` is now `reflectionThresholdTokens`, and `observationThresholdTokens` is new. Old v1 keys are silently ignored — update your `settings.json`.
 
 ## Commands
 
-| Command | Description |
+| Command | What it does |
 |---|---|
-| `/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 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.
+| `/om-status` | Memory totals, percent-to-threshold for each gate, and in-flight flags for observer and compaction |
+| `/om-view` | Full dump of memory state: every reflection, every committed observation, every pending observation. Each observation line is `[id] YYYY-MM-DD HH:MM [relevance] content` |
 
-**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.
+## Credits
 
-**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.
+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.
 
 ## License
 

package/package.json

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

package/src/branch.ts

@@ -0,0 +1,190 @@
+import {
+	OBSERVATION_CUSTOM_TYPE,
+	isMemoryDetails,
+	isObservationEntryData,
+	type MemoryDetails,
+	type ObservationEntryData,
+	type ObservationRecord,
+	type Reflection,
+} from "./types.js";
+import { estimateEntryTokens } from "./tokens.js";
+
+type Entry = {
+	type: string;
+	id: string;
+	timestamp?: string;
+	message?: unknown;
+	content?: unknown;
+	customType?: string;
+	summary?: unknown;
+	fromId?: string;
+	data?: unknown;
+	details?: unknown;
+	firstKeptEntryId?: string;
+};
+
+const RAW_TYPES = new Set(["message", "custom_message", "branch_summary"]);
+
+function isObservationEntry(entry: Entry): boolean {
+	return entry.type === "custom" && entry.customType === OBSERVATION_CUSTOM_TYPE;
+}
+
+export function findLastCompactionIndex(entries: Entry[]): number {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].type === "compaction") return i;
+	}
+	return -1;
+}
+
+export function lastObservationCoverEndIdx(entries: Entry[]): number {
+	const idToIdx = new Map<string, number>();
+	for (let i = 0; i < entries.length; i++) idToIdx.set(entries[i].id, i);
+	let maxIdx = -1;
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (!isObservationEntry(entry)) continue;
+		if (!isObservationEntryData(entry.data)) continue;
+		const coverIdx = idToIdx.get(entry.data.coversUpToId);
+		if (coverIdx !== undefined && coverIdx > maxIdx) maxIdx = coverIdx;
+	}
+	return maxIdx;
+}
+
+function rawTokensFromIndex(entries: Entry[], startIndex: number): number {
+	let total = 0;
+	for (let i = Math.max(0, startIndex); i < entries.length; i++) {
+		if (RAW_TYPES.has(entries[i].type)) total += estimateEntryTokens(entries[i]);
+	}
+	return total;
+}
+
+export function rawTokensSinceLastBound(entries: Entry[]): number {
+	return rawTokensFromIndex(entries, lastObservationCoverEndIdx(entries) + 1);
+}
+
+export function rawTokensSinceLastCompaction(entries: Entry[]): number {
+	const compactionIdx = findLastCompactionIndex(entries);
+	if (compactionIdx === -1) return rawTokensFromIndex(entries, 0);
+	return rawTokensFromIndex(entries, liveTailStartIndex(entries));
+}
+
+function liveTailStartIndex(entries: Entry[]): number {
+	const compactionIdx = findLastCompactionIndex(entries);
+	if (compactionIdx === -1) return 0;
+	const firstKept = entries[compactionIdx].firstKeptEntryId;
+	if (!firstKept) throw new Error("compaction entry missing firstKeptEntryId");
+	const firstKeptIdx = entries.findIndex((e) => e.id === firstKept);
+	if (firstKeptIdx === -1) throw new Error(`firstKeptEntryId "${firstKept}" not found in entries`);
+	return firstKeptIdx;
+}
+
+export function firstRawIdAfter(entries: Entry[], afterIndex: number): string | undefined {
+	for (let i = Math.max(0, afterIndex + 1); i < entries.length; i++) {
+		if (RAW_TYPES.has(entries[i].type)) return entries[i].id;
+	}
+	return undefined;
+}
+
+export function gapRawEntries(entries: Entry[], newFirstKeptEntryId: string): Entry[] {
+	const lastBoundIdx = lastObservationCoverEndIdx(entries);
+	const newKeptIdx = entries.findIndex((e) => e.id === newFirstKeptEntryId);
+	if (newKeptIdx === -1) return [];
+	const result: Entry[] = [];
+	for (let i = lastBoundIdx + 1; i < newKeptIdx; i++) {
+		if (RAW_TYPES.has(entries[i].type)) result.push(entries[i]);
+	}
+	return result;
+}
+
+export function rawTailEntriesBetween(entries: Entry[], fromId: string, untilId: string): Entry[] {
+	const fromIdx = entries.findIndex((e) => e.id === fromId);
+	const untilIdx = entries.findIndex((e) => e.id === untilId);
+	if (fromIdx === -1 || untilIdx === -1 || untilIdx < fromIdx) return [];
+
+	const result: Entry[] = [];
+	for (let i = fromIdx; i <= untilIdx; i++) {
+		if (RAW_TYPES.has(entries[i].type)) result.push(entries[i]);
+	}
+	return result;
+}
+
+function getPriorMemoryDetails(entries: Entry[]): MemoryDetails | undefined {
+	const idx = findLastCompactionIndex(entries);
+	if (idx === -1) return undefined;
+	const details = entries[idx].details;
+	return isMemoryDetails(details) ? details : undefined;
+}
+
+export function collectObservationsByCoverage(
+	entries: Entry[],
+	priorFirstKeptEntryId: string | undefined,
+	newFirstKeptEntryId: string,
+): ObservationEntryData[] {
+	const idToIdx = new Map<string, number>();
+	for (let i = 0; i < entries.length; i++) idToIdx.set(entries[i].id, i);
+
+	const newFKIIdx = idToIdx.get(newFirstKeptEntryId);
+	if (newFKIIdx === undefined) return [];
+
+	let priorFKIIdx: number;
+	if (priorFirstKeptEntryId === undefined) {
+		priorFKIIdx = -1;
+	} else {
+		const idx = idToIdx.get(priorFirstKeptEntryId);
+		if (idx === undefined) throw new Error(`priorFirstKeptEntryId "${priorFirstKeptEntryId}" not found in entries`);
+		priorFKIIdx = idx;
+	}
+
+	const result: ObservationEntryData[] = [];
+	for (const entry of entries) {
+		if (!isObservationEntry(entry)) continue;
+		if (!isObservationEntryData(entry.data)) continue;
+		const fromIdx = idToIdx.get(entry.data.coversFromId);
+		if (fromIdx === undefined) continue;
+		if (fromIdx >= priorFKIIdx && fromIdx < newFKIIdx) result.push(entry.data);
+	}
+	return result;
+}
+
+function collectObservationsPendingNextCompaction(entries: Entry[]): ObservationEntryData[] {
+	const idToIdx = new Map<string, number>();
+	for (let i = 0; i < entries.length; i++) idToIdx.set(entries[i].id, i);
+
+	const priorCompactionIdx = findLastCompactionIndex(entries);
+	let thresholdIdx: number;
+	if (priorCompactionIdx === -1) {
+		thresholdIdx = -1;
+	} else {
+		const priorFirstKept = entries[priorCompactionIdx].firstKeptEntryId;
+		if (!priorFirstKept) throw new Error("prior compaction entry missing firstKeptEntryId");
+		const idx = idToIdx.get(priorFirstKept);
+		if (idx === undefined) throw new Error(`prior firstKeptEntryId "${priorFirstKept}" not found in entries`);
+		thresholdIdx = idx;
+	}
+
+	const result: ObservationEntryData[] = [];
+	for (const entry of entries) {
+		if (!isObservationEntry(entry)) continue;
+		if (!isObservationEntryData(entry.data)) continue;
+		const fromIdx = idToIdx.get(entry.data.coversFromId);
+		if (fromIdx === undefined) continue;
+		if (fromIdx >= thresholdIdx) result.push(entry.data);
+	}
+	return result;
+}
+
+export interface MemoryState {
+	reflections: Reflection[];
+	committedObs: ObservationRecord[];
+	pendingObs: ObservationRecord[];
+}
+
+export function getMemoryState(entries: Entry[]): MemoryState {
+	const priorDetails = getPriorMemoryDetails(entries);
+	const pendingData = collectObservationsPendingNextCompaction(entries);
+	return {
+		reflections: priorDetails?.reflections ?? [],
+		committedObs: priorDetails?.observations ?? [],
+		pendingObs: pendingData.flatMap((d) => d.records),
+	};
+}

package/src/commands/status.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { SettingsManager } from "@mariozechner/pi-coding-agent";
+import {
+	getMemoryState,
+	rawTokensSinceLastBound,
+	rawTokensSinceLastCompaction,
+} from "../branch.js";
+import { countByRelevance, formatRelevanceHistogram } from "../relevance.js";
+import type { Runtime } from "../runtime.js";
+import { estimateStringTokens } from "../tokens.js";
+
+export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void {
+	pi.registerCommand("om-status", {
+		description: "Show observational memory status",
+		handler: async (_args, ctx) => {
+			runtime.ensureConfig(ctx.cwd);
+			const entries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastBound>[0];
+			const sinceBound = rawTokensSinceLastBound(entries);
+			const sinceCompaction = rawTokensSinceLastCompaction(entries);
+
+			const { reflections: committedRefs, committedObs, pendingObs } = getMemoryState(entries);
+			const committedObsTokens = committedObs.reduce((s, r) => s + estimateStringTokens(r.content), 0);
+			const committedObsCount = committedObs.length;
+			const committedRefsTokens = committedRefs.reduce((s, r) => s + estimateStringTokens(r), 0);
+			const committedRefsCount = committedRefs.length;
+
+			const pendingObsTokens = pendingObs.reduce((s, r) => s + estimateStringTokens(r.content), 0);
+			const pendingObsCount = pendingObs.length;
+
+			const relevanceHistogram = countByRelevance([...committedObs, ...pendingObs]);
+
+			const keepRecentTokens = SettingsManager.create(ctx.cwd).getCompactionKeepRecentTokens();
+
+			const obsThreshold = runtime.config.observationThresholdTokens;
+			const compThreshold = runtime.config.compactionThresholdTokens;
+			const refThreshold = runtime.config.reflectionThresholdTokens;
+			// Approximation: the real compaction gate excludes pending obs whose coversFromId falls inside
+			// the new keep-recent tail (deferred to next cycle) and adds any sync-catch-up gap obs produced
+			// at compaction entry. We over-count by the tail slice and can't predict the gap obs here.
+			// Precise version would simulate the new firstKeptEntryId by walking back keepRecentTokens from
+			// the branch tail and split pending into pre-tail vs tail-covering.
+			const observationPoolTokens = committedObsTokens + pendingObsTokens;
+			const obsPct = Math.min(100, Math.round((sinceBound / obsThreshold) * 100));
+			const compPct = Math.min(100, Math.round((sinceCompaction / compThreshold) * 100));
+			const refPct = Math.min(100, Math.round((observationPoolTokens / refThreshold) * 100));
+
+			const refLabel = committedRefsCount === 1 ? "entry" : "entries";
+			const cObsLabel = committedObsCount === 1 ? "observation" : "observations";
+			const pObsLabel = pendingObsCount === 1 ? "observation" : "observations";
+
+			const lines = [
+				"── Memory ──",
+				`Reflections:   ~${committedRefsTokens.toLocaleString()} tokens (${committedRefsCount} ${refLabel})      — durable insights`,
+				`Observations:`,
+				`  committed    ~${committedObsTokens.toLocaleString()} tokens (${committedObsCount} ${cObsLabel}) — folded into last compaction`,
+				`  pending      ~${pendingObsTokens.toLocaleString()} tokens (${pendingObsCount} ${pObsLabel}) — waiting for next compaction`,
+				`  relevance    ${formatRelevanceHistogram(relevanceHistogram)}`,
+				"",
+				"── Activity ──",
+				`Next observation: ~${sinceBound.toLocaleString()} / ${obsThreshold.toLocaleString()} tokens (${obsPct}%)`,
+				`  → at ${obsThreshold.toLocaleString()} tokens, recent conversation is compressed into new observations`,
+				`Next compaction:  ~${sinceCompaction.toLocaleString()} / ${compThreshold.toLocaleString()} tokens (${compPct}%)`,
+				`  → at ${compThreshold.toLocaleString()} tokens, raw history is replaced by the updated reflections and`,
+				`    observations, keeping only the last ${keepRecentTokens.toLocaleString()} tokens of conversation verbatim`,
+				`Next reflection:  ~${observationPoolTokens.toLocaleString()} / ${refThreshold.toLocaleString()} tokens (${refPct}%)`,
+				`  → if observations exceed ${refThreshold.toLocaleString()} tokens when compaction runs, reflections are`,
+				`    distilled from them and redundant observations are pruned away`,
+			];
+
+			if (runtime.observerInFlight || runtime.compactInFlight) {
+				lines.push("");
+				lines.push("── In flight ──");
+				if (runtime.observerInFlight) lines.push("Observer: running");
+				if (runtime.compactInFlight) lines.push("Compaction: running");
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/src/commands/view.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getMemoryState } from "../branch.js";
+import { countByRelevance, formatRelevanceHistogram } from "../relevance.js";
+import type { Runtime } from "../runtime.js";
+import { estimateStringTokens } from "../tokens.js";
+import type { ObservationRecord } from "../types.js";
+
+export function registerViewCommand(pi: ExtensionAPI, runtime: Runtime): void {
+	pi.registerCommand("om-view", {
+		description: "Print observational memory details (reflections + observations)",
+		handler: async (_args, ctx) => {
+			runtime.ensureConfig(ctx.cwd);
+			const entries = ctx.sessionManager.getBranch() as Parameters<typeof getMemoryState>[0];
+			const { reflections: committedRefs, committedObs, pendingObs } = getMemoryState(entries);
+
+			const committedRefTokens = committedRefs.reduce((s, r) => s + estimateStringTokens(r), 0);
+			const committedRefCount = committedRefs.length;
+
+			const committedObsTokens = committedObs.reduce((s, r) => s + estimateStringTokens(r.content), 0);
+			const committedObsCount = committedObs.length;
+
+			const pendingObsTokens = pendingObs.reduce((s, r) => s + estimateStringTokens(r.content), 0);
+			const pendingObsCount = pendingObs.length;
+
+			const totalObsCount = committedObsCount + pendingObsCount;
+			const totalTokens = committedRefTokens + committedObsTokens + pendingObsTokens;
+			const relevanceHistogram = countByRelevance([...committedObs, ...pendingObs]);
+
+			const plural = (n: number, singular: string, plural: string) => (n === 1 ? singular : plural);
+			const renderObs = (r: ObservationRecord) =>
+				`[${r.id}] ${r.timestamp} [${r.relevance}] ${r.content}`;
+
+			const sections: string[] = [];
+
+			sections.push(
+				`Memory: ${committedRefCount} ${plural(committedRefCount, "reflection", "reflections")} · ` +
+					`${totalObsCount} ${plural(totalObsCount, "observation", "observations")} ` +
+					`(${committedObsCount} committed, ${pendingObsCount} pending) · ` +
+					`~${totalTokens.toLocaleString()} tokens · ` +
+					`relevance ${formatRelevanceHistogram(relevanceHistogram)}`,
+			);
+			sections.push("");
+
+			sections.push(
+				`── Reflections (${committedRefCount} ${plural(committedRefCount, "entry", "entries")}, ~${committedRefTokens.toLocaleString()} tokens) ──`,
+			);
+			if (committedRefs.length > 0) {
+				sections.push(committedRefs.join("\n\n"));
+			} else {
+				sections.push("(none)");
+			}
+
+			sections.push("");
+			sections.push(
+				`── Observations — committed (${committedObsCount} ${plural(committedObsCount, "observation", "observations")}, ~${committedObsTokens.toLocaleString()} tokens) ──`,
+			);
+			if (committedObs.length > 0) {
+				sections.push(committedObs.map(renderObs).join("\n"));
+			} else {
+				sections.push("(none)");
+			}
+
+			sections.push("");
+			sections.push(
+				`── Observations — pending (${pendingObsCount} ${plural(pendingObsCount, "observation", "observations")}, ~${pendingObsTokens.toLocaleString()} tokens) ──`,
+			);
+			if (pendingObs.length > 0) {
+				sections.push(pendingObs.map(renderObs).join("\n"));
+			} else {
+				sections.push("(none)");
+			}
+
+			sections.push("");
+			sections.push("Tip: use /tree to browse the raw messages still live in the session.");
+
+			ctx.ui.notify(sections.join("\n"), "info");
+		},
+	});
+}