pi-blackhole

Deterministic compaction + session-aware observational memory for Pi — in one unified extension.

/blackhole replaces Pi's LLM-based /compact with an algorithmic structural summary — fast, zero-cost. Three background workers (Observer, Reflector, Dropper) capture durable facts and decisions that survive across compactions. Per-worker model fallback chains with persisted cooldowns. Manual flush mode. One JSON file to configure it all.

Install

# From npm (recommended)
pi install npm:pi-blackhole

# Or directly from GitHub.
# Requires npmCommand to be set in settings.json, otherwise pi runs
# `npm install --omit=dev`, devDependencies are skipped, and dist/ is not built.
# Example: "npmCommand": ["npm"] in ~/.pi/agent/settings.json
pi install git:github.com/k0valik/pi-blackhole

If you have standalone pi-vcc or pi-observational-memory installed, remove them first — they conflict and will prevent blackhole from loading:

pi uninstall npm / git:https://github.com/sting8k/pi-vcc
pi uninstall npm / git:https://github.com/elpapi42/pi-observational-memory

Then /reload or restart Pi. The config file at ~/.pi/agent/pi-blackhole/pi-blackhole-config.json is created with sensible defaults — no setup required for the default behavior. Config merges global → project → env → session (session is ephemeral). See docs/CONFIG.md for tuning or run /blackhole settings to open the interactive overlay.

Want a guided setup? Pass llms.txt to your agent — it will walk you through the interview, including picking cheap fallback models for your providers.

✨ What's new

Latest release: 0.5.9

• Recall drill-downs can no longer flood your context — every #N:path / #N:text expansion is capped by recallResponseMaxChars, and the cap names where to pick up (continue at #42:src/auth.ts:412:30), so a minified bundle or a huge write no longer dumps itself into the prompt.
• Quiet sessions — showWorkerNotifications: false silences routine observer/reflector/dropper progress toasts; warnings, errors, and /blackhole* command output stay visible.
• Worker prompt caching is tunable per install — cacheRetention: none | short | long is forwarded to all three worker streams, and unset inherits Pi's effective setting.
• A hung worker model fails on a clock, not a hope — new workerAttemptTimeoutMs bounds the whole agent loop (header waits, heartbeats, tool turns) per attempt; configured candidates then enter their normal cooldown and fallback chain.
• Finished worker runs stop early — record_observations / record_reflections accept a complete flag, so a fully-processed run ends instead of spending its agentMaxTurns budget.
• Dropper pool pressure now works end to end — gated on observationsPoolMaxTokens (the same pool the footer P gauge shows), it bypasses new-data gates and 1.0 disables it.

See CHANGELOG.md for the full history.

What it does

Long engineering sessions degrade. Pi's native /compact calls an LLM to write a free-form prose summary — then compacts that summary, then compacts the next. After a few cycles, load-bearing details vanish: why a decision was made, which approaches were rejected, what the user clarified early on. The session is still alive; the agent has stopped carrying the real context.

pi-blackhole solves this in two complementary ways:

• Algorithmic compaction — a deterministic, zero-cost compile() pipeline extracts structured sections (goal, files, commits, preferences, brief transcript) and replaces the old conversation with one compact block. No LLM is called for compaction itself.
• Observational memory — three background workers (Observer → Reflector → Dropper) run during the session, capturing timestamped facts and distilling durable reflections in a session ledger that survives every compaction.

Both halves share a single hook and a single output. Together they keep the agent's context sharp across arbitrarily long sessions — without the cost, drift, or erosion of repeated LLM-based summarization.

Commands

All commands work regardless of compaction mode — only when auto-compaction fires changes. See Compaction modes below.

Compaction modes

Two modes, one shared goal: keep your agent's context sharp without manual housekeeping. (compaction: "off" is a third escape hatch that hands everything back to Pi.)

Manual mode is the maintainer's daily driver: workers still run, but observations accumulate in <sessionId>-pending.json files instead of cluttering the conversation. /blackhole flushes the buffer, runs algorithmic compaction, and injects durable reflections in one shot.

compaction: "off" + memory: false (or PI_BLACKHOLE_PASSIVE=true) completely disables all background workers and blackhole's auto-compaction — useful for debugging or comparing against Pi's native path. Explicit /blackhole still works in this mode.

Who owns the compaction?

With the default compactionEngine: "blackhole", blackhole's session_before_compact hook owns every compaction Pi initiates — threshold auto-compact, overflow recovery, and /compact — replacing Pi's LLM summarizer with the deterministic pipeline. The only exception is defensive: if both the VCC summary and the OM projection come up empty (a pathological all-noise transcript), blackhole declines and Pi's native summarizer runs, so you never get a context-free replacement. With compactionEngine: "pi-default", compaction: "manual", or compaction: "off", Pi handles everything except explicit /blackhole. See docs/CONFIG.md → compactionEngine for the full interaction matrix.

How does /blackhole compare to /compact?

• /compact calls an LLM to write a free-form summary — costly, lossy, no memory layer.
• /blackhole uses algorithmic section extraction (goals, files, commits, preferences…) plus injects observations and reflections from the session ledger. No LLM is involved in the compaction itself. Fast, deterministic, memory-preserving - the observational memory pipeline's arrived results apply instantly on compaction.

/blackhole is essentially a single /compact that just works — especially in manual mode.

How it works

When /blackhole fires (manually or via the auto-trigger), two things happen in one shot:

1. The vcc pipeline analyzes the transcript tail and produces a structured summary: session goal, file changes, commits, outstanding blockers, user preferences, and a rolling brief transcript. Deterministic — same input always produces the same output.
2. Observational memory injection renders accumulated observations and reflections from the session ledger and appends them below the summary.

The agent receives a deterministic recap of recent work plus durable facts from the full session history — in a single replacement block. No LLM was called for the compaction itself.

Quick start config

Defaults target ~128k context models and work out of the box — no tuning required. To keep costs low, set cheap models for the background workers (the only required change for most setups):

{
  "observerModel": { "provider": "openrouter", "id": "qwen/qwen3-next-80b-a3b-instruct:free" },
  "reflectorModel": { "provider": "cerebras", "id": "gpt-oss-120b" },
  "dropperModel": { "provider": "cerebras", "id": "gpt-oss-120b" }
}

Fallbacks (optional): each worker tries stageModel → stageFallbacks → base model → session model (skipping cooled-down models). By default the workers do not fall back to your session model — this avoids surprise cost and cache busting. Enable it with sessionFallback: true (default) or set model as a shared fallback. See docs/CONFIG.md → Model Configuration.

Config file: ~/.pi/agent/pi-blackhole/pi-blackhole-config.json

Full reference — every key, default, and env override — lives in:

• 📘 docs/CONFIG.md — authoritative config reference. Start here for tuning.
• 🤖 llms.txt — agent-facing interview. Pass it to your agent for a guided setup.
• 📦 example-config.json — annotated example with fallback rationale and thinking levels.

Demo

/blackhole collapses ~143k tokens of conversation into a ~6.3k structured summary (YMMV based on your settings). /blackhole-memory shows pipeline status. /blackhole-recall searches history — the agent can do the same via its recall tool.

https://github.com/user-attachments/assets/a7dd804d-6aca-4bdb-8b6e-0dd779363a43

The three memory workers

Three background workers (separate LLM calls) run automatically during the session when memory: true (the default):

• Observer — reads conversation since the last observation marker and extracts timestamped facts: events, decisions, preferences. Input is capped to observerChunkMaxTokens newest-first to prevent context blowup on long sessions. Runs most frequently.
• Reflector — distills new observations into durable reflections: stable facts, patterns, and constraints that survive future compactions. Runs less often.
• Dropper — prunes low-value observations from active memory when the pool exceeds observationsPoolMaxTokens, while keeping reflections and other long-term elements safely in the session ledger.

[Conversation turn] ──> (accumulated tokens >= observeAfterTokens)
                            │
                            v
                    1. OBSERVER   (extracts timestamped observations)
                            │
                            v
                    2. REFLECTOR  (synthesizes durable reflections)
                            │
                            v
                    3. DROPPER    (prunes low-value observations)

Each worker uses an agentLoop with tool-calling capabilities — they don't just make a single LLM call. The observer, for example, can call record_observations multiple times per run to work through a chunk incrementally.

If any stage fails (model error, rate limit, timeout), remaining stages are skipped and the full pipeline retries on the next agent_start or turn_end. A 30-second retry gate prevents hammering failing APIs. Within each stage, the runtime tries all configured fallback models before giving up — each failed model is cooled down and skipped in subsequent attempts.

[Session Goal]
- Fix the authentication bug in login flow
- [Scope change]
- Also update the session token refresh logic

[Files And Changes]
- Modified: src/auth/session.ts
- Created: tests/auth-refresh.test.ts

[Commits]
- a1b2c3d: fix(auth): refresh token after password reset

[Outstanding Context]
- lint check still failing on line 42

[User Preferences]
- Prefer Vietnamese responses
- Always run tests before committing

[user]
Fix the auth bug...

[assistant]
Root cause is a missing token refresh...
...transcript continues...

---
The conversation before this point has been compacted into the summary above.
Details not captured here — exact code, error messages, file paths — are only recoverable via `recall`.
Use `recall` to search the session history. Do not redo work already completed.

## Reflections
[c3d4e5f6a1b2] User is building Acme Dashboard on Next.js 15 with Supabase auth.

## Observations
[a1b2c3d4e5f6] 2026-05-23 [high] User decided to switch from REST to GraphQL; motivation was reducing over-fetching.
[b2c3d4e5f6a1] 2026-05-23 [medium] GraphQL migration completed; user confirmed working.

----
Bracketed ids in reflections and observations connect to their source session entries.
These are condensed memories from earlier in this session.
When entries conflict, the most recent observation reflects the latest known state.
Use `recall` with an id to retrieve original context.
----

Uninstall

pi uninstall git:github.com/k0valik/pi-blackhole
rm -rf ~/.pi/agent/pi-blackhole

Documentation map

Note: All docs except README.md, CHANGELOG.md (package root, read by /blackhole changelog), and llms.txt live under docs/ — product docs (architecture.md, CONFIG.md, etc.); archived_docs/ is local-only (gitignored).

Credits

pi-blackhole started as a merge of two upstream projects but has since diverged significantly. The codebase still carries DNA from both:

• pi-vcc by @sting8k — algorithmic conversation compaction (the compile() pipeline, section extraction, recall core).
• pi-observational-memory by @elpapi42 — session-ledger-based observation/reflection capture, memory agents, ledger folding.

What blackhole adds and reworks on top:

• Unified configuration — one JSON file, not two.
• Per-worker model fallback chains with persisted cooldowns that survive Pi restarts.
• Manual flush mode — compaction: "manual" saves observations to per-session disk buffers.
• Conflict resolution — OM hooks into vcc's compaction, not Pi's default.
• Memory toggle (/blackhole om-off / /blackhole om-on) — disable the memory layer without uninstalling.
• Per-session pending state — isolated per-session JSON files, no cross-session contamination.
• Custom provider bridge — consolidation agents loaded via jiti can still use provider stream functions registered by other extensions.
• Retryable error detection with per-model cooldowns — models that fail get cooled down, fallbacks tried automatically, 30-second retry gate prevents spam.
• Improved observer/reflector/dropper prompts — each heavily customized with detailed extraction rules, relevance guidance, and error handling.
• OM-recall coupling — when expanding session entries via recall, related observations and reflections are automatically shown.
• Thinking level support — per-model thinking field for reasoning effort control, including max where supported by the provider.

License

MIT