pi-blackhole 0.3.1 → 0.3.2

package/README.md

@@ -1,5 +1,12 @@
 # pi-blackhole
 
+> [!NOTE]
+> **For blackhole to handle all compaction automatically**, set `"overrideDefaultCompaction": true` in your config at
+> `~/.pi/agent/pi-blackhole/pi-blackhole-config.json`. Without this, blackhole stays out of Pi's compaction by default
+> and only activates via the `/blackhole` command.
+>
+> See [`CONFIG.md`](CONFIG.md) for the full reference.
+
 **Algorithmic compaction + session-aware observational memory for [Pi](https://github.com/badlogic/pi-mono) — in one unified extension.**
 
 Blackhole merges the best ideas from [pi-vcc](https://github.com/sting8k/pi-vcc) and [pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) into something that's become its own beast entirely. Deterministic compaction that costs nothing. A memory layer that survives compactions. Per-worker model fallback chains with persisted cooldowns. Manual flush mode. All configured from one JSON file.
@@ -8,6 +15,21 @@ Blackhole merges the best ideas from [pi-vcc](https://github.com/sting8k/pi-vcc)
 >
 > The codebase has since diverged heavily from both upstreams, but tries to keep up-to-date with any fixes from them..
 
+> [!IMPORTANT]
+> **Auto-compaction behavior & configuration**
+>
+> Blackhole's auto-compaction **only activates when explicitly opted in**. By default (`overrideDefaultCompaction: false`), blackhole stays out of Pi's compaction — Pi handles its own automatically, and blackhole's `/blackhole` command still works manually.
+>
+> Configure via your Pi agent's `config.json`:
+>
+> | What you want | `overrideDefaultCompaction` | `noAutoCompact` |
+> |---|---|---|
+> | Blackhole auto-compacts at your threshold | `true` | `false` |
+> | Pi handles auto-compaction (default) | `false` | `false` |
+> | Manual only — use `/blackhole` | any | `true` |
+>
+> See [`CONFIG.md`](CONFIG.md) for the full reference.
+
 📖 See [`CHANGELOG.md`](CHANGELOG.md) for release history.
 ⚙️ See [`CONFIG.md`](CONFIG.md) for the full configuration reference.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-blackhole",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "packageManager": "pnpm@11.2.2",
   "description": "Unified compaction + observational memory extension for Pi — compresses conversation context while preserving durable observations and reflections",
   "license": "MIT",

package/src/om/compaction-trigger.ts

@@ -24,6 +24,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 			passive: runtime.config.passive,
 			memory: runtime.config.memory,
 			noAutoCompact: runtime.config.noAutoCompact,
+			overrideDefaultCompaction: runtime.config.overrideDefaultCompaction,
 			compactInFlight: runtime.compactInFlight,
 			compactAfterTokens: runtime.config.compactAfterTokens,
 		});
@@ -40,6 +41,13 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 			dbg("compaction_trigger.skip", { reason: "noAutoCompact" });
 			return;
 		}
+		// Don't force Pi to compact unless the user explicitly opted into blackhole's pipeline.
+		// When overrideDefaultCompaction is false (default), blackhole stays out of the way
+		// and lets Pi handle its own compaction naturally.
+		if (runtime.config.overrideDefaultCompaction === false) {
+			dbg("compaction_trigger.skip", { reason: "overrideDefaultCompaction_false" });
+			return;
+		}
 		if (runtime.compactInFlight) {
 			dbg("compaction_trigger.skip", { reason: "compactInFlight" });
 			return;