pi-observational-memory 3.0.1 → 3.0.3

package/README.md

@@ -208,6 +208,8 @@ A typical config:
     "observeAfterTokens": 10000,
     "reflectAfterTokens": 20000,
     "compactAfterTokens": 81000,
+    "compactAfterTokensMode": "calibrated",
+    "compactAfterTokensRatio": 0.68,
     "observationsPoolMaxTokens": 20000,
     "observationsPoolTargetTokens": 10000,
     "agentMaxTurns": 16,
@@ -224,13 +226,52 @@ A typical config:
 
 Most users can start with the defaults and tune only if they have a specific reason.
 
+### Scaling compaction to the model's context window
+
+By default `compactAfterTokensMode` is `"calibrated"`, so the proactive
+compaction trigger fires at the fixed `compactAfterTokens` value (81,000 by
+default). That is backwards-compatible and works well for typical ~128K–200K
+context models.
+
+On a large-context model (e.g. 1M tokens) the calibrated default preempts
+compaction at ~81K, wasting most of the window. Switch to `"ratio"` mode to let
+the trigger scale with the active model's `contextWindow`:
+
+```json
+{
+  "observational-memory": {
+    "compactAfterTokens": 81000,
+    "compactAfterTokensMode": "ratio",
+    "compactAfterTokensRatio": 0.5
+  }
+}
+```
+
+In ratio mode the effective threshold is
+`floor(model.contextWindow * compactAfterTokensRatio)` (clamped to a minimum of
+1). With the example above, a 1,000,000-token window compacts at ~500,000 raw
+tokens; a 200,000-token window compacts at ~100,000.
+
+`compactAfterTokensRatio` is user-tunable precisely because **context window ≠
+attention**. Some models advertise a large window but degrade at long range; set
+a lower ratio (e.g. `0.4`) to compact earlier on those, or a higher ratio
+(e.g. `0.7`) on models that stay sharp. The default ratio is `0.68`.
+
+`compactAfterTokens` is always retained as the fallback: in `"calibrated"`
+mode it is the threshold directly, and in `"ratio"` mode it is used whenever
+the active model's `contextWindow` is unavailable (undefined, 0, or negative),
+so compaction still triggers safely. `/om:status` shows the resolved threshold
+on the `Next compaction` line regardless of mode.
+
 ### Defaults
 
 | Setting                     | Default       | Meaning                                                                                           |
 | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
 | `observeAfterTokens`        | `10000`       | Raw/source token threshold for observation runs.                                                  |
 | `reflectAfterTokens`        | `20000`       | Raw/source token threshold for reflection runs; successful reflection creates dropper opportunities. |
-| `compactAfterTokens`        | `81000`       | Raw/source token threshold for proactive auto-compaction.                                         |
+| `compactAfterTokens`        | `81000`       | Raw/source token threshold for proactive auto-compaction (used directly in `"calibrated"` mode, and as the fallback in `"ratio"` mode). |
+| `compactAfterTokensMode`    | `"calibrated"`| `"calibrated"` uses `compactAfterTokens` directly (default, backwards-compatible). `"ratio"` scales the threshold by the active model's `contextWindow`. |
+| `compactAfterTokensRatio`   | `0.68`        | In `"ratio"` mode, the threshold is `floor(contextWindow * ratio)`. Tunable because large windows do not always mean strong long-range attention. Must be in `(0, 1)`. |
 | `observationsPoolMaxTokens` | `20000`       | Observation-token budget used for compaction full-fold pressure.                                  |
 | `observationsPoolTargetTokens` | half of max | Active observation target used by post-reflection dropper maintenance.                            |
 | `agentMaxTurns`             | `16`          | Shared turn cap for background memory-agent loops.                                                |
@@ -263,12 +304,12 @@ For details and tuning guidance, see [`docs/configuration.md`](docs/configuratio
 
 | Surface             | What it does                                                                                                                                    |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/om-status`        | Shows memory counts, plain `+N` / `-N` visible/full drift suffixes, progress clocks, visible and active observation pool pressure, passive/in-flight state, and last worker errors. |
-| `/om-view`          | Shows current visible memory and attempts to copy the rendered memory text to the clipboard.                                                   |
-| `/om-view full`     | Shows the full current memory state for the branch and attempts to copy the rendered memory text to the clipboard.                             |
+| `/om:status`        | Shows memory counts, plain `+N` / `-N` visible/full drift suffixes, progress clocks, visible and active observation pool pressure, passive/in-flight state, and last worker errors. |
+| `/om:view`          | Shows current visible memory and attempts to copy the rendered memory text to the clipboard.                                                   |
+| `/om:view full`     | Shows the full current memory state for the branch and attempts to copy the rendered memory text to the clipboard.                             |
 | `recall` agent tool | Recovers source evidence for a 12-character observation/reflection id on the current branch. It is not semantic search or a transcript browser. |
 
-`/om-view` copies only the rendered memory content. The success/failure line shown in Pi is not included in the clipboard text. If clipboard support is unavailable, the command still prints the memory view and shows a warning. Before the first V3 compaction, visible memory can be empty because nothing has been folded into `om.folded` details; use `/om-view full` to inspect recorded branch memory.
+`/om:view` copies only the rendered memory content. The success/failure line shown in Pi is not included in the clipboard text. If clipboard support is unavailable, the command still prints the memory view and shows a warning. Before the first V3 compaction, visible memory can be empty because nothing has been folded into `om.folded` details; use `/om:view full` to inspect recorded branch memory.
 
 ---
 
@@ -310,7 +351,7 @@ Current behavior:
 * **Fast compaction.** `session_before_compact` does not call a model or wait for background workers. It renders the current prepared memory state.
 * **Background memory work.** Observation and reflection work run from `turn_end` when their token clocks are due; dropper work runs only after successful reflection and prunes the folded active observation ledger toward `observationsPoolTargetTokens`.
 * **Source-backed recall.** Observations and reflections can be traced back through the `recall` tool.
-* **Visible/full views.** `/om-view` shows visible memory and `/om-view full` shows the full current memory state. Use `/om-status` for visible-vs-full drift and for the separate visible observation pool vs active observation pool.
+* **Visible/full views.** `/om:view` shows visible memory and `/om:view full` shows the full current memory state. Use `/om:status` for visible-vs-full drift and for the separate visible observation pool vs active observation pool.
 * **No V2 compatibility layer.** Old V2 settings and memory entries are ignored rather than migrated.
 
 ---

package/package.json

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

package/src/commands/status.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { observationPoolMetrics } from "../agents/dropper/pool.js";
+import { resolveCompactAfterTokens } from "../config.js";
 import type { Runtime } from "../runtime.js";
 import {
 	diffProjection,
@@ -13,7 +14,7 @@ import {
 } from "../session-ledger/index.js";
 
 function pct(current: number, total: number): number {
-	return total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 0;
+	return total > 0 ? Math.round((current / total) * 100) : 0;
 }
 
 function tokenSum(items: { tokenCount: number }[]): number {
@@ -34,7 +35,7 @@ function appendSuffixes(line: string, suffixes: (string | undefined)[]): string
 }
 
 export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void {
-	pi.registerCommand("om-status", {
+	pi.registerCommand("om:status", {
 		description: "Show observational memory status",
 		handler: async (_args, ctx) => {
 			runtime.ensureConfig(ctx.cwd);
@@ -61,6 +62,8 @@ export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void
 			const obsProgress = rawTokensSinceObservationCoverage(entries);
 			const reflectionProgress = rawTokensSinceReflectionCoverage(entries);
 			const compactionProgress = rawTokensSinceLastCompaction(entries);
+			const contextWindow = typeof ctx.model?.contextWindow === "number" ? ctx.model.contextWindow : undefined;
+			const compactThreshold = resolveCompactAfterTokens(runtime.config, contextWindow);
 
 			const passiveLines = runtime.config.passive === true
 				? [
@@ -79,7 +82,7 @@ export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void
 				"── Activity ──",
 				`Next observation: ~${obsProgress.toLocaleString()} / ${runtime.config.observeAfterTokens.toLocaleString()} tokens (${pct(obsProgress, runtime.config.observeAfterTokens)}%)`,
 				`Next reflection:  ~${reflectionProgress.toLocaleString()} / ${runtime.config.reflectAfterTokens.toLocaleString()} tokens (${pct(reflectionProgress, runtime.config.reflectAfterTokens)}%)`,
-				`Next compaction:  ~${compactionProgress.toLocaleString()} / ${runtime.config.compactAfterTokens.toLocaleString()} tokens (${pct(compactionProgress, runtime.config.compactAfterTokens)}%)`,
+				`Next compaction:  ~${compactionProgress.toLocaleString()} / ${compactThreshold.toLocaleString()} tokens (${pct(compactionProgress, compactThreshold)}%)`,
 				`Visible observation pool: ~${visibleObservationTokens.toLocaleString()} / ${runtime.config.observationsPoolMaxTokens.toLocaleString()} tokens (${pct(visibleObservationTokens, runtime.config.observationsPoolMaxTokens)}%)`,
 				`Active observation pool: ~${activeObservationPool.observationTokens.toLocaleString()} / ${runtime.config.observationsPoolTargetTokens.toLocaleString()} target tokens (${pct(activeObservationPool.observationTokens, runtime.config.observationsPoolTargetTokens)}%)`,
 				`Reflection pool:         ~${visibleReflectionTokens.toLocaleString()} tokens`,

package/src/commands/view.ts

@@ -41,7 +41,7 @@ interface ViewCommandOptions {
 export function registerViewCommand(pi: ExtensionAPI, runtime: Runtime, options: ViewCommandOptions = {}): void {
 	const copyToClipboard = options.copyToClipboard ?? copyTextToClipboard;
 
-	pi.registerCommand("om-view", {
+	pi.registerCommand("om:view", {
 		description: "Print and copy observational memory content (visible by default, full for recorded memory)",
 		handler: async (args, ctx) => {
 			runtime.ensureConfig(ctx.cwd);
@@ -52,8 +52,8 @@ export function registerViewCommand(pi: ExtensionAPI, runtime: Runtime, options:
 				const copied = await copyToClipboard(output).catch(() => false);
 				ctx.ui.notify(
 					copied
-						? `${output}\n\nCopied /om-view output to clipboard.`
-						: `${output}\n\nWarning: failed to copy /om-view output to clipboard.`,
+						? `${output}\n\nCopied /om:view output to clipboard.`
+						: `${output}\n\nWarning: failed to copy /om:view output to clipboard.`,
 					"info",
 				);
 			};
@@ -64,7 +64,7 @@ export function registerViewCommand(pi: ExtensionAPI, runtime: Runtime, options:
 			}
 
 			if (mode && mode !== "visible") {
-				ctx.ui.notify("Usage: /om-view [full]", "info");
+				ctx.ui.notify("Usage: /om:view [full]", "info");
 				return;
 			}
 

package/src/config.ts

@@ -9,10 +9,33 @@ export interface ConfiguredModel {
 	thinking?: ModelThinkingLevel;
 }
 
+/**
+ * How `compactAfterTokens` is interpreted.
+ *
+ * - `"calibrated"` (default): use the static `compactAfterTokens` value directly.
+ *   Backwards-compatible with all existing V3 configs.
+ *
+ * - `"ratio"`: compute the effective threshold as
+ *   `floor(model.contextWindow * compactAfterTokensRatio)`. This auto-scales the
+ *   proactive compaction trigger to the active model's context window, so a 1M
+ *   context model is not preempted at the same 81K threshold as a 128K model.
+ *
+ *   Some models advertise a large context window but lose attention at long
+ *   range; users can lower `compactAfterTokensRatio` to compact earlier on such
+ *   models without giving up the window on models that stay sharp.
+ *
+ *   When the active model's `contextWindow` is unavailable (undefined, 0, or
+ *   negative), ratio mode falls back to the calibrated `compactAfterTokens`
+ *   value so compaction still triggers safely.
+ */
+export type CompactAfterTokensMode = "calibrated" | "ratio";
+
 export interface Config {
 	observeAfterTokens: number;
 	reflectAfterTokens: number;
 	compactAfterTokens: number;
+	compactAfterTokensMode: CompactAfterTokensMode;
+	compactAfterTokensRatio: number;
 	observationsPoolMaxTokens: number;
 	observationsPoolTargetTokens: number;
 	agentMaxTurns: number;
@@ -25,6 +48,8 @@ export const DEFAULTS: Config = {
 	observeAfterTokens: 10_000,
 	reflectAfterTokens: 20_000,
 	compactAfterTokens: 81_000,
+	compactAfterTokensMode: "calibrated",
+	compactAfterTokensRatio: 0.68,
 	observationsPoolMaxTokens: 20_000,
 	observationsPoolTargetTokens: 10_000,
 	agentMaxTurns: 16,
@@ -32,6 +57,25 @@ export const DEFAULTS: Config = {
 	debugLog: false,
 };
 
+export const COMPACT_AFTER_TOKENS_MODE_VALUES: readonly CompactAfterTokensMode[] = ["calibrated", "ratio"] as const;
+
+/**
+ * Resolve the effective proactive-compaction token threshold for the given
+ * config and active model context window.
+ *
+ * In `"calibrated"` mode this is always `config.compactAfterTokens`.
+ *
+ * In `"ratio"` mode this is `floor(contextWindow * compactAfterTokensRatio)`
+ * (clamped to a minimum of 1) when `contextWindow` is a positive number, and
+ * falls back to `config.compactAfterTokens` otherwise.
+ */
+export function resolveCompactAfterTokens(config: Config, contextWindow: number | undefined): number {
+	if (config.compactAfterTokensMode === "ratio" && typeof contextWindow === "number" && contextWindow > 0) {
+		return Math.max(1, Math.floor(contextWindow * config.compactAfterTokensRatio));
+	}
+	return config.compactAfterTokens;
+}
+
 export const THINKING_LEVEL_VALUES: readonly ModelThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 
 const SETTINGS_KEY = "observational-memory";
@@ -54,6 +98,19 @@ function isThinkingLevel(value: unknown): value is ModelThinkingLevel {
 	return typeof value === "string" && (THINKING_LEVEL_VALUES as readonly string[]).includes(value);
 }
 
+function isCompactAfterTokensMode(value: unknown): value is CompactAfterTokensMode {
+	return typeof value === "string" && (COMPACT_AFTER_TOKENS_MODE_VALUES as readonly string[]).includes(value);
+}
+
+/**
+ * A valid ratio is a finite number strictly between 0 and 1.
+ * 0 would never trigger; >= 1 would compact at/after the full window with no
+ * room left for the response.
+ */
+function validRatioOrUndefined(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value < 1 ? value : undefined;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
@@ -86,6 +143,11 @@ function normalizeSettingsConfig(value: Record<string, unknown>): Partial<Config
 		const normalizedValue = positiveIntegerOrUndefined(value[key]);
 		if (normalizedValue !== undefined) normalized[key] = normalizedValue;
 	}
+	if (isCompactAfterTokensMode(value.compactAfterTokensMode)) {
+		normalized.compactAfterTokensMode = value.compactAfterTokensMode;
+	}
+	const ratio = validRatioOrUndefined(value.compactAfterTokensRatio);
+	if (ratio !== undefined) normalized.compactAfterTokensRatio = ratio;
 	if (typeof value.passive === "boolean") normalized.passive = value.passive;
 	if (typeof value.debugLog === "boolean") normalized.debugLog = value.debugLog;
 	const model = normalizeModel(value.model);

package/src/hooks/compaction-trigger.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveCompactAfterTokens } from "../config.js";
 import { rawTokensSinceLastCompaction, type Entry } from "../session-ledger/index.js";
 import type { Runtime } from "../runtime.js";
 
@@ -33,7 +34,12 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 
 		const entries = ctx.sessionManager.getBranch() as Entry[];
 		const tokens = rawTokensSinceLastCompaction(entries);
-		if (tokens < runtime.config.compactAfterTokens) return;
+		// Resolve the proactive-compaction threshold from the active model's context
+		// window when ratio mode is configured. ctx.model is the current session model
+		// (Model<any> | undefined per ExtensionContext).
+		const contextWindow = typeof ctx.model?.contextWindow === "number" ? ctx.model.contextWindow : undefined;
+		const threshold = resolveCompactAfterTokens(runtime.config, contextWindow);
+		if (tokens < threshold) return;
 
 		// Capture ctx properties synchronously — the setTimeout + async work below
 		// may outlive the extension ctx (stale after session replacement/reload).
@@ -58,7 +64,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 				}
 				const currentEntries = ctx.sessionManager.getBranch() as Entry[];
 				const currentTokens = rawTokensSinceLastCompaction(currentEntries);
-				if (currentTokens < runtime.config.compactAfterTokens) {
+				if (currentTokens < threshold) {
 					runtime.compactInFlight = false;
 					if (hasUI) ui?.notify(
 						"Observational memory: compaction skipped — another compaction already ran before deferred compaction",

package/src/tools/recall-observation.ts

@@ -453,7 +453,7 @@ export const recallObservationTool = defineTool({
 	parameters: Type.Object({
 		id: Type.String({
 			pattern: "^[a-f0-9]{12}$",
-			description: "12-character lowercase hex observation or reflection id shown in compacted memory, /om-view, or a previous recall result. Must be a specific id; this tool does not search by topic.",
+			description: "12-character lowercase hex observation or reflection id shown in compacted memory, /om:view, or a previous recall result. Must be a specific id; this tool does not search by topic.",
 		}),
 	}),
 	renderCall(args) {